﻿<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet href="swscheme2.xsl" type="text/xsl"?>
<!DOCTYPE doc [
  <!ELEMENT doc (maintitle, section*)>
  <!ELEMENT maintitle (#PCDATA)>
  <!ELEMENT section (title, (p|ul|ulp|section)*)>
  <!ATTLIST section name CDATA #IMPLIED>
  <!ELEMENT title (#PCDATA)>
  <!ELEMENT ul (li|ul)*>
  <!ELEMENT ulp (li|ul|ulp)*>
  <!ELEMENT li (#PCDATA | code | var | i | b | xref | link)*>
  <!ELEMENT p (#PCDATA | code | var | i | b | xref | link)*>
  <!ELEMENT code (#PCDATA | var)*>
  <!ELEMENT var (#PCDATA)>
  <!ELEMENT xref EMPTY>
  <!ATTLIST xref dest CDATA #IMPLIED>
  <!ELEMENT link (#PCDATA)>
  <!ATTLIST link url CDATA #IMPLIED>
  <!ELEMENT i (#PCDATA)>
  <!ELEMENT b (#PCDATA)>
  <!ENTITY lt "&#38;#60;">
  <!ENTITY gt "&#62;">
  <!ENTITY amp "&#38;#38;">
  <!ENTITY apos "&#39;">
  <!ENTITY quot "&#34;">
  <!ENTITY ndash "&#8211;">
  <!ENTITY mdash "&#8212;">
  <!ENTITY lsquo "&#8216;">
  <!ENTITY rsquo "&#8217;">
  <!ENTITY ldquo "&#8220;">
  <!ENTITY rdquo "&#8221;">
]>
<!-- formatted to 118 chars width -->
<doc>

<maintitle>Sunlit World Scheme</maintitle>

<section name="intro"><title>Introduction</title>

<p>(This document is part of Sunlit World Scheme, Copyright © 2010 by Edward Kiser. Licensed under the terms of the
GNU General Public License, version 2 or later. All other rights reserved.)</p>

<p>Scheme is an elegant programming language that allows you to construct a program out of a collection of simple but
powerful nestable building blocks.</p>

<p>Sunlit World Scheme is my own implementation. It is a work in progress and, at present, only partially conforms to
the Scheme standards.</p>

<p>This instruction manual is written to describe what building blocks are available. It assumes prior knowledge of
programming, and, in cases where it can&rsquo;t be helped, it assumes prior knowledge of Scheme.</p>

<section name="rationale"><title>Why Sunlit World Scheme?</title>

<p>Sunlit World Scheme can do things that no other Scheme can do. It&rsquo;s exactly that simple. This manual
documents the sorts of things that Sunlit World Scheme can do. If you want a Scheme that can do these things, then
Sunlit World Scheme is the Scheme for you.</p>

<p>Sunlit World Scheme is designed to emphasize interactive graphics, sockets, asynchronous message passing, and
low-level bit and byte manipulation. It is also designed to be very easy to extend.</p>

<p>Sunlit World Scheme was started a long time ago, when other Scheme implementations were less mature than they are
today. There are a few things that other Schemes can do that Sunlit World Scheme cannot do. If you need those things,
then you would probably be happier with another Scheme
implementation. (<link url="http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Main_Page">Gambit Scheme</link> is
pretty good. If you need another Scheme that is compatible with dot-Net,
consider <link url="http://ironscheme.codeplex.com/">Iron Scheme</link>.)</p>

</section>

<section name="notational"><title>Notational Conventions</title>

<p>This document looks best in Firefox although it seems to be legible in Internet Explorer. (IE7 and IE8 don&rsquo;t
seem to handle the title of the &ldquo;And&rdquo; and &ldquo;Or&rdquo; section quite right, or entities generally in
some cases). IE6 has not been tested.</p>

<p><code>This font</code> is used for code, which must be typed exactly as shown.</p>

<p><var>This font</var> is used for variables, which must be replaced with appropriate values.</p>

<p>If a variable is followed by ellipses, zero or more instances of the variable may occur. In other words, where this
document calls for <code>(<var>blah</var> <var>...</var>)</code>, <code>()</code> is acceptable. If one or more
instances are required, the requirement will be written as <code>(<var>blah</var> <var>blah</var>
<var>...</var>)</code>.</p>

</section>

</section>

<section name="datatypes"><title>Data Types</title>

<p>Scheme is a <i>weakly typed</i> language. A data item knows its own type (which makes Scheme more strongly typed
than Forth or assembly language), but a variable, a parameter, or an argument can be of any type.</p>

<p>Here are the types supported by Sunlit World Scheme.</p>

<section name="boolean"><title>Booleans</title>

<p>The booleans are <code>#t</code> (true) and <code>#f</code> (false).</p>

</section>

<section name="integers"><title>Integers</title>

<p>Sunlit World Scheme supports arbitrary-precision integers.</p>

<p>An integer is written as an optional sign (<code>+</code> or <code>-</code>) followed by a sequence of one or more
decimal digits. Examples include <code>4578926458734658237456</code> and <code>-1</code>. A integer can be written in
hexadecimal as an optional sign followed by <code>#x</code> followed by a sequence of one or more hexadecimal digits,
for example <code>-#x100</code>. The hexadecimal digits <code>A</code> through <code>F</code> are
case-insensitive. Sunlit World Scheme cannot currently read an octal integer, but there are functions to convert
between integers and digit strings in bases 2 through 36.</p>

</section>

<section name="rationals"><title>Rationals</title>

<p>A rational is written with an optional sign, followed by a sequence of one or more decimal digits, followed by a
slash, followed by another sequence of one or more decimal digits. For example, <code>1/2</code> or
<code>-2/3</code>.</p>

<p>Rationals, like integers, are exact and have arbitrary precision.</p>

</section>

<section name="floats"><title>Floating-Point Numbers</title>

<p>Sunlit World Scheme uses IEEE 64-bit floating-point numbers for inexact math.</p>

<p>There are several ways in which a floating-point number may be written. The most common form is like an integer but
with a decimal point somewhere among the digits. The decimal point must come after the optional
sign. <code>-3.5</code>, <code>-35.</code>, and <code>+.35</code> are all floats. It is also possible to create a
floating-point number that has an exponent. In this case, an explicit decimal point is not required. The sign of the
exponent is presumed to be <code>+</code> if not specified. Floating-point numbers with exponents include
<code>1.E+10</code>, <code>1E10</code>, and <code>-2E-3</code>.</p>

<p>See also <xref dest="func_math"/>.</p>

</section>

<section name="vec3d"><title>3-D Geometry</title>

<p>Sunlit World Scheme supports several types for exact 3-D geometry.</p>

<ulp>

<li><b>Vectors.</b> A 3-D vector is written <code>#vec3(<var>x</var> <var>y</var> <var>z</var>)</code>
where <var>x</var>, <var>y</var>, and <var>z</var> are integers or rational numbers. Vectors are used to represent
displacements.</li>

<li><b>Vertices.</b> A 3-D vertex is written <code>#vtx3(<var>x</var> <var>y</var> <var>z</var>)</code>
where <var>x</var>, <var>y</var>, and <var>z</var> are integers or rational numbers. Vertices are used to represent
positions in 3-D space.</li>

<li><b>Lines.</b> A 3-D line object cannot be entered directly, but can be returned as a function result. 3-D lines
are infinite.</li>

<li><b>Planes.</b> A 3-D plane object cannot be entered directly, but can be returned as a function result. 3-D planes
are infinite.</li>

<li><b>Convex Hulls.</b> A 3-D convex hull represents a shape described by the convex hull of zero or more points.</li>

</ulp>

<p>Functions are available to compute dot and cross products of vectors, to find the intersections of various
geometric forms, and to build convex hulls incrementally.</p>

<p>See also <xref dest="geometry"/>.</p>

</section>

<section name="characters"><title>Characters</title>

<p>Sunlit World Scheme, like the underlying dot-Net platform, uses 16-bit characters.</p>

<p>A character is written as <code>#\</code> followed by the character. This includes:</p>

<ul>
<li><code>#\#</code></li>
<li><code>#\\</code></li>
<li><code>#\(</code></li>
<li><code>#\)</code></li>
</ul>

<p>and so forth. Characters written in this way never get confused with other types of values. Some characters have
names instead:</p>

<ul>
<li><code>#\nul</code></li>
<li><code>#\bel</code></li>
<li><code>#\backspace</code></li>
<li><code>#\tab</code></li>
<li><code>#\newline</code></li>
<li><code>#\vt</code></li>
<li><code>#\page</code></li>
<li><code>#\return</code></li>
<li><code>#\space</code></li>
</ul>

<p>Finally, there is a way to specify 16-bit Unicode characters that cannot be represented by the codes above:</p>

<ul>
<li><code>#\x<var>code</var></code>, where <var>code</var> is a four-digit hexadecimal character code from
<code>0000</code> to <code>FFFF</code>. The hexadecimal digits <code>A</code> through <code>F</code> are
case-insensitive.</li>
</ul>

<p>Unicode code points above <code>65535</code> cannot be represented as single characters, and must be encoded using
surrogate pairs. Sunlit World Scheme imitates dot-Net by using the &ldquo;character&rdquo; type to represent an
unpaired surrogate.</p>

</section>

<section name="strings"><title>Strings</title>

<p>A string is a sequence of characters. As in standard Scheme, strings may be modified in place, but their length
cannot be changed.</p>

<p>A string is written as a begin-quote followed by a sequence of zero or more characters followed by an end-quote,
such as <code>""</code> (the empty string) or <code>"hello"</code>.</p>

<p>The backslash character <code>\</code> is used to mark escapes. Single character escapes are the same as in C
(<code>\&quot;</code>, <code>\\</code>, <code>\a</code> bell, <code>\b</code> backspace, <code>\t</code> tab,
<code>\n</code> newline, <code>\v</code> vertical tab, <code>\f</code> form feed, <code>\r</code> return), with the
addition of <code>\e</code> for escape.</p>

<p>Octal and hex escapes of the form <code>\<var>oct</var></code> and <code>\x<var>hex</var></code> are also supported
in strings, but only for characters 0-255. <var>oct</var> must be three digits and can range from <code>000</code>
to <code>377</code>, and <var>hex</var> must be two digits from <code>00</code> to <code>FF</code>. The hexadecimal
digits <code>A</code> through <code>F</code> are case-insensitive.</p>

<p>The implementation supports Unicode in strings. Characters are 16-bit; Unicode code points above <code>65535</code>
must be encoded using surrogate pairs. An extended hex escape can be used to specify any representable character,
regardless of whether it is representable by the escape codes above. It is written <code>\u<var>code</var></code>,
where <var>code</var> is replaced with any four-digit hexadecimal number, from <code>0000</code>
to <code>FFFF</code>.</p>

<p>See also <xref dest="func_strings"/>.</p>

</section>

<section name="symbols"><title>Symbols</title>

<p>A symbol is similar to a string, but symbols are immutable, and symbols with the same characters are guaranteed to
be equal. A symbol can be written as a string with pipe symbols, like <code>|abc|</code>, and all the same escapes can
be used in symbols that are used in strings, except that double-quotes do not need to be escaped and pipe symbols
do. In cases where no confusion with non-symbols is possible, the starting and ending pipes of a symbol may be
omitted, thus <code>abc</code> is the same as <code>|abc|</code>.</p>

</section>

<section name="lists"><title>Lists and Improper Lists</title>

<p>Lists are one of the fundamental data types of Scheme.</p>

<p>The empty list is represented as <code>()</code>. It may have spaces between the parentheses; such spaces are
ignored.</p>

<p>A non-empty list is represented by one or more <i>cons cells</i>, which are also known as <i>pairs</i>. A cons cell
is a record with two fields, a <i>car</i> and a <i>cdr</i>. The car contains the first item in the list, the
<i>head</i>, and the cdr contains the rest of the list, or <i>tail</i>.</p>

<p>The list <code>(1)</code> consists of a single cons cell. The car is the integer <code>1</code> and the cdr is
<code>()</code>, the empty list.</p>

<p>The list <code>(1 2 3)</code> consists of a cons cell whose car is <code>1</code> and whose cdr is the list
<code>(2 3)</code>, which in turn consists of a cons cell whose car is <code>2</code> and whose cdr is the list
<code>(3)</code>, and so forth.</p>

<p>The tail of a list is expected to be another list, including possibly the empty list. However, a cons cell does not
enforce this restriction, and it is possible to store any item in the cdr field of a cons cell. This gives rise to the
need for <i>dotted lists</i>, also known as <i>improper lists</i>.</p>

<p>The dotted list <code>(1 . 2)</code> consists of a cons cell whose car is <code>1</code> and whose cdr is
<code>2</code>. The dotted list <code>(1 2 . 3)</code> is a cons cell whose car is <code>1</code> and whose cdr is the
improper list <code>(2 . 3)</code>.</p>

<p>See also <xref dest="func_lists"/>.</p>

</section>

<section name="vector"><title>Vectors</title>

<p>A vector is written the same way as a list, but with the addition of a leading pound sign. <code>#(1 2 3)</code> is
a vector with three elements. A vector is stored as a deque of <code>object</code> and there are ways to change the
size of the vector by adding or removing items to or from either end. Dotted vectors are impossible.</p>

<p>See also <xref dest="func_vectors"/>.</p>

</section>

<section name="hashsetsandmaps"><title>Hash Sets and Hash Maps</title>

<p>A hash set is written the same way as a list, but with the addition of a leading pound sign and an <code>s</code>
meaning &ldquo;set.&rdquo; <code>#s(1 2 3)</code> is a set with three elements. The order of the elements does not
matter, and may vary. Only hashable items may be stored in a hash set.</p>

<p>A hash map is written the same way as a hash set, except that every item is required to be a pair. Only the first
item in the pair has to be hashable. Thus, <code>#m((one . 1) (two . 2) (three . 3))</code> is a hash map.</p>

<p>(If the second item in the pair is a list, the whole item will be printed as a list. Therefore, <code>#m((1 2
3))</code> is a valid hash map. It contains one pair. The key is <code>1</code> and the value for that key is the list
<code>(2 3)</code>.)</p>

<p>See also <xref dest="recursiveeval"/> and <xref dest="hashset"/>.</p>

</section>

<section name="messagesandsignatures"><title>Messages and Signatures</title>

<p>Messages and signatures are used by the object system. They can also be used in the same manner as Objective
Caml&rsquo;s &ldquo;variant types,&rdquo; or F#&rsquo;s &ldquo;discriminated unions.&rdquo;</p>

<p>A message has a type and zero or more key-value pairs known as arguments. The type must be a symbol, and the keys
of the arguments must be symbols. The values of the arguments can be of any Scheme type.</p>

<p>A signature has a type and zero or more parameters. The type must be a symbol and the parameters must be
symbols.</p>

<p>Every message has a corresponding signature with the same type symbol. The message&rsquo;s argument keys must be
the same as the corresponding signature&rsquo;s parameters.</p>

<p>A message with no arguments is written <code>#msg(<var>type</var>)</code>. A message with one or more arguments is
written <code>#msg(<var>type</var> . <var>key1</var> <var>value1</var> <var>key2</var> <var>value2</var>
<var>...</var>)</code>.</p>

<p>A signature with no parameters is written <code>#sig(<var>type</var>)</code>. A signature with one or more
parameters is written <code>#sig(<var>type</var> . <var>key1</var> <var>key2</var> <var>...</var>)</code>.</p>

<p>Arguments and parameters are order-insensitive.</p>

<p>See also <xref dest="recursiveeval"/>, <xref dest="mcase"/>, <xref dest="messagelambdas"/>,
<xref dest="func_messagesandsignatures"/>, and <xref dest="func_objects"/>.</p>

</section>

<section name="ipaddr"><title>IP Addresses and Endpoints</title>

<p>IP addresses are rarely typed literally, but it is possible.</p>

<p>An IPv4 address is written <code>#ipv4[<var>n</var>.<var>n</var>.<var>n</var>.<var>n</var>]</code>, where each
<var>n</var> is a number from <code>0</code> to <code>255</code> inclusive.</p>

<p>An IPv4 endpoint is an address followed by <code>:</code> and a port number from <code>0</code> to <code>65535</code>.
(I am not sure port zero is actually available.)</p>

<p>An IPv6 address is written <code>#ipv6[<var>addr</var>]</code>, where <var>addr</var> is a string consisting of
hexadecimals and colons. The exact format of the string is part of the IPv6 specification. Strings that do not match
the format cause lexical errors.</p>

<p>An IPv6 endpoint is an IPv6 address followed by <code>:</code> and a port number from <code>0</code> to
<code>65535</code>.</p>

<p>See also <xref dest="networking"/>.</p>

</section>

<section name="bytearray"><title>Byte Arrays, Byte Ranges, and Byte Rectangles</title>

<p>Objects of these types cannot be entered at the prompt, but they are very powerful and are commonly used for
I/O.</p>

<p>See also <xref dest="func_bytes"/>, <xref dest="byterange"/>, and <xref dest="byterect"/>.</p>

</section>

<section name="procedures"><title>Procedures</title>

<p>Procedures and functions are first-class values in Scheme. You cannot type a procedure directly, although you can
type an expression that produces a procedure. Scheme cannot display a procedure directly, either.</p>

<p>A <i>continuation</i> is a special type of procedure. A continuation is a function analogous to the
&ldquo;return&rdquo; statement in other languages. In Scheme, continuations can be captured. Sunlit World Scheme
supports continuations of unlimited extent, which means that a continuation remains valid after it has been
used. Scheme&rsquo;s &ldquo;stack frames&rdquo; persist, and are only deleted by garbage collection after they become
unreachable. A function can return its own continuation, and if this continuation is used, it gives the effect of the
function returning more than once. Continuations can be used to set up co-routines.</p>

<p>(However, continuations cannot be used to move from one thread to another.)</p>

<p>See also <xref dest="func_proc"/>.</p>

</section>

<section name="unspecified"><title>The Unspecified Value</title>

<p>Many procedures and syntaxes in Scheme return an <i>unspecified value.</i> The Scheme specification uses this term
to say that the procedure or syntax may return anything. However, many Scheme implementations have defined an actual
&ldquo;unspecified value&rdquo; and cause those procedures and syntaxes to return it. This Scheme follows that
tradition.</p>

</section>

<section name="other"><title>Other Types</title>

<p>Sunlit World Scheme supports many other types; in fact it uses the dot-Net <code>System.Object</code> type as its
underlying type, so any dot-Net object could appear as a parameter or result.</p>

</section>

</section>

<section name="syntaxes"><title>Syntaxes</title>

<p>In Scheme, a program is (typically) a list. The list is evaluated and the result printed on the screen.</p>

<p>Evaluation includes identifying syntaxes (and syntax errors) in the list. It is usually recursive.</p>

<p>Here are the syntaxes supported by Sunlit World Scheme.</p>

<section name="literals"><title>Self-Evaluating Literals</title>

<p>Booleans, integers, rationals, floats, characters, signatures, strings, 3-D vectors, and 3-D vertices evaluate to
themselves.</p>

</section>

<section name="quotation"><title>Quotation</title>

<p>The <code>quote</code> syntax has two forms, a long form and a short form.</p>

<ulp>

<li><b>The Short Form</b> is <code>'<var>data</var></code>. (The <code>'</code> is an apostrophe.)</li>

<li><b>The Long Form</b> is <code>(quote <var>data</var>)</code>.</li>

</ulp>

<p>The two forms are indistinguishable to the interpreter.</p>

<p>The form <code>(quote <var>data</var>)</code> always evaluates to <var>data</var>. This means that quoting one of
the self-evaluating data types above has no effect. But the point of <code>quote</code> is that it allows you to pass
literal lists, symbols, vectors, hash sets, or hash maps to functions. The evaluator would normally attempt to
interpret a list as a syntax and a symbol as a variable reference. A vector is traditionally
non-evaluable. <code>quote</code> causes
<var>data</var> to pass through the interpreter without being evaluated.</p>

</section>

<section name="quasiquotation"><title>Quasiquotation</title>

<p>Quasiquotation can be used to build new lists and vectors which consist of a combination of unchanging and changing
parts.</p>

<p>A syntax has the form <code>(quasiquote <var>qqdata</var>)</code> or <code>`<var>qqdata</var></code>. (The
<code>`</code> is a back-tick.)</p>

<p>The <var>qqdata</var> is examined by the quasiquote mechanism.</p>

<p>If <var>qqdata</var> contains <code>,<var>expr</var></code> or <code>(unquote <var>expr</var>)</code>, then
<var>expr</var> is evaluated and its value is substituted in place of the <code>,<var>expr</var></code> or
<code>(unquote <var>expr</var>)</code>.</p>

<p>If <var>qqdata</var> contains <code>,@<var>expr</var></code> or <code>(unquote-splicing <var>expr</var>)</code> in
a list, then <var>expr</var> is evaluated with the expectation that it evaluates to a list, and the list is spliced
into the place of <code>,@<var>expr</var></code> or <code>(unquote-splicing <var>expr</var>)</code>.</p>

<p>It is an error for an <code>unquote</code> or <code>unquote-splicing</code> form to appear outside of a
<code>quasiquote</code> form. It is an error for <code>unquote-splicing</code> to appear outside of a list, although
it is not an error for it to appear at the beginning or end of a list.</p>

<p>If <var>qqdata</var> contains a nested <code>`<var>qqdata</var></code> or <code>(quasiquote
<var>qqdata</var>)</code>, then <var>qqdata</var> is examined with a higher &ldquo;nesting count.&rdquo; Inside of a
nested <code>quasiquote</code>, nestings of <code>unquote</code> and <code>unquote-splicing</code> are detected. If
and only if they are nested to the same depth, then <var>expr</var> is evaluated and the substitution is made at the
bottom level of nesting. If <code>unquote</code>s and <code>unquote-splicing</code>s are not nested to sufficient
depth, then they are copied verbatim to the output.</p>

<p>Quasiquotation does not work with hash sets, hash maps, signatures, or messages.</p>

</section>

<section name="recursiveeval"><title>Recursively Evaluable Types</title>

<p>A couple of types are recursively evaluable. In other words, if an object of one of these types is presented for
evaluation, it is taken apart, some of the parts are evaluated, and then a new object is constructed replacing the
evaluated expressions with their values.</p>

<p>The hash map is one of these types. The keys are not evaluated, but the values are. Evaluating <code>#m((a . (+ 3
2)) (b . (+ 4 5)))</code> will give the result <code>#m((a . 5) (b . 9))</code>.</p>

<p>The other recursively evaluable type is the message. The type of the message and the argument keys are not
evaluted, but the argument values are evaluated. Evaluating <code>#msg(test . a (+ 7 1) b (+ 8 1))</code> will give
the result <code>#msg(test . a 8 b 9)</code>.</p>

<p>This was done to make up for the fact that these data types are not amenable to quasiquotation.</p>

<p>Evaluation always constructs and returns a new object.</p>

</section>

<section name="varref"><title>Variable References</title>

<p>Symbols such as <code>quote</code> are considered syntactic keywords. All symbols that are not syntactic keywords
are considered variable references.</p>

<p>The variable must be defined in the scope of its reference, or else it is an error.</p>

</section>

<section name="set"><title>set!</title>

<p>The syntax <code>(set! <var>var</var> <var>value</var>)</code> is used to change the value of a variable. The
<var>value</var> expression is evaluated recursively.</p>

<p>This syntax returns the unspecified value.</p>

<p>When a variable is first created, it is bound to a box in memory, and the contents are stored in the box. You can
change the contents of the box, but you cannot change which box a variable is bound to.</p>

</section>

<section name="begin"><title>Sequences</title>

<p>The syntax <code>(begin <var>item</var> <var>...</var>)</code> allows zero or more items to be evaluated in
sequence. If one or more items is provided, the value of the last is returned. If zero items are provided, the
unspecified value is returned.</p>

</section>

<section name="if"><title>If-then-else</title>

<p>The syntax <code>(if <var>test</var> <var>consequence</var> <var>alternate</var>)</code> represents an if-then-else
statement.</p>

<p>The syntax <code>(if <var>test</var> <var>consequence</var>)</code> is also valid.</p>

<p>First, <var>test</var> is evaluated. If it is <code>#f</code>, then the <var>alternate</var> is evaluated and its
value is returned. (If there is no <var>alternate</var>, the unspecified value is returned.) If the <var>test</var>
evaluates to non-<code>#f</code>, the <var>consequence</var> is evaluated and its value returned.</p>

</section>

<section name="cond"><title>Cond</title>

<p>The syntax <code>(cond <var>clause</var> <var>...</var>)</code> works like the &ldquo;if, else-if, else-if,
else&rdquo; found in other languages.</p>

<p>Each clause is of the form <code>(<var>test</var> <var>body</var> <var>...</var>)</code>. The <var>body</var> forms
are treated as if enclosed in a <code>begin</code>.</p>

<p>The <var>test</var> expression is evaluated. If the result is non-<code>#f</code>, the <var>body</var> forms for
that <var>clause</var> are evaluated and the result of the last one is returned. If the result is <code>#f</code>,
execution moves to the next <var>clause</var>.</p>

<p>The last clause may have a <var>test</var> of <code>else</code>, which causes the last clause to always be
executed.</p>

<p>If the <var>test</var> of the last clause fails, the unspecified value is returned.</p>

</section>

<section name="case"><title>Case</title>

<p>The syntax <code>(case <var>datum</var> <var>clause</var> <var>...</var>)</code> evaluates the expression for
<var>datum</var>, then uses a hash table to determine which <var>clause</var> should be executed. If <var>datum</var>
is not found and an <code>else</code> clause has been specified, the <code>else</code> clause is executed. The value
of the <code>case</code> form is the value of the last form in the clause that was executed.</p>

<p>The syntax of a <var>clause</var> is <code>((<var>item1</var> <var>item2</var> <var>...</var>) <var>action1</var>
<var>action2</var> ...)</code>. The <var>items</var> are not evaluated. Non-hashable <var>items</var> are ignored.</p>

</section>

<section name="mcase"><title>Message Case</title>

<p>The syntax <code>(mcase <var>datum</var> <var>clause</var> <var>...</var>)</code> evaluates the expression
for <var>datum</var>, expecting it to be a message. Then it binds variables for the message arguments and executes
the <var>clause</var> that matches the message, or, if none matches, the <code>else</code> clause.</p>

<p>The syntax of a <var>clause</var> is <code>(<var>msg</var> <var>body</var> <var>...</var>)</code>. The <var>msg</var>
must be either a message whose arguments are symbols to be bound to the actual message that matches, or a signature,
in which case the names of the symbols bound will be the names of the parameters.</p>

<p>For example, when <code>x</code> is <code>#msg(test . x 100 y 200)</code>:</p>

<ul>

<li>The expression <code>(mcase x (#msg(test . x a y b) (list a b)) (else #f))</code> will evaluate to <code>(100
200)</code>.</li>

<li>The expression <code>(mcase x (#sig(test . x y) (list x y)) (else #f))</code> will also evaluate to <code>(100
200)</code>.</li>

</ul>

</section>

<section name="local"><title>Object Fields (&ldquo;Locals&rdquo;)</title>

<p>Inside a Scheme object&rsquo;s message handler, it is possible to refer to the object&rsquo;s fields with the
<code>(local <var>var</var>)</code> syntax. <var>var</var> must be a symbol naming the object field being
referenced. <var>var</var> is not evaluated.</p>

<p>This syntax could not have been <code>(field <var>var</var>)</code> because there is a function
called <code>field</code> which is used for dot-Net reflection.</p>

<p>A field can be set with the syntax <code>(set!
(local <var>var</var>) <var>value</var>)</code>. Only <var>value</var> is evaluated.</p>

</section>

<section name="andor"><title>&ldquo;And&rdquo; And &ldquo;Or&rdquo;</title>

<p>Scheme supports short-circuiting <code>and</code> and <code>or</code> syntaxes.</p>

<p>They take the forms <code>(and <var>expr</var> <var>...</var>)</code> and <code>(or <var>expr</var>
<var>...</var>)</code>.</p>

<p>If <code>and</code> is called with zero <var>expr</var>s, it returns <code>#f</code>. If <code>or</code> is called
with zero <var>expr</var>s, it returns <code>#t</code>.</p>

<p>Otherwise <code>and</code> evaluates the forms from left to right, but if any <var>expr</var> returns
<code>#f</code>, <code>and</code> stops and returns <code>#f</code>. <code>or</code> evaluates from left to right, but
if any <var>expr</var> returns non-<code>#f</code>, <code>or</code> stops and returns that value.</p>

</section>

<section name="funcall"><title>Invocations</title>

<p><i>Invocations</i> are also known as <i>function calls</i> or <i>procedure calls.</i></p>

<p>The syntax of an invocation is <code>(<var>func</var> <var>arg</var> <var>...</var>)</code>.</p>

<p>The syntax permits zero or more <var>arg</var>s, but the proper number depends on which function is being
invoked.</p>

<p>The <var>func</var> and each <var>arg</var> are evaluated in some unspecified order.</p>

<p>The <var>func</var> is typically a reference to a variable that contains a function, but it can be any syntax that
evaluates to a function. Sunlit World Scheme includes several pre-defined functions, which are documented in the
section on functions.</p>

<p>Once evaluations of the subforms are complete, the function is invoked with the arguments and the value is
returned.</p>

</section>

<section name="lambdas"><title>Lambdas</title>

<p>The <code>lambda</code> syntax creates and returns a procedure. Its syntax is <code>(lambda <var>arglist</var>
<var>body</var> <var>...</var>)</code>.</p>

<p>The <var>arglist</var> can take any of these four forms.</p>

<ulp>

<li><b>An empty list,</b> <code>()</code>. This creates a function that does not take any arguments.</li>

<li><b>A list of symbols,</b> such as <code>(a b)</code>. This creates a function that takes exactly as many arguments
as there are symbols in the list. When the function is called, the arguments are bound, in order, to variables denoted
by the symbols.</li>

<li><b>An improper list of symbols,</b> such as <code>(a b . c)</code>. This creates a function that requires at least
as many arguments as there are variables before the dot, but may take zero or more additional arguments. The required
arguments are bound to the variables named by the symbols; the additional arguments are placed in order into a list,
which is then bound to the variable named by the symbol after the dot.</li>

<li><b>A single symbol,</b> such as <code>x</code>. This creates a function that takes zero or more arguments. All the
arguments that are passed are placed in order into a list, which is then bound to a single variable named by the
symbol.</li>

</ulp>

<p>The <var>body</var> may consist of zero or more expressions. It acts just like a <code>begin</code>. The
<var>body</var> is evaluated each time the function is called.</p>

<p>In Scheme, <code>lambda</code> captures variables. What this means is that if you reference a variable inside a
function which is not created directly inside that function and is not a parameter, the function object will contain a
reference directly to the box where that variable&rsquo;s value is stored. The function will continue to refer to that
box, even in contexts where the same name leads to a different box.</p>

</section>

<section name="messagelambdas"><title>Message Lambdas</title>

<p>The <code>mlambda</code> syntax creates and returns a <i>message procedure</i>. Message procedures are used by the
object system and cannot be invoked using the ordinary invocation syntax. (There is a function that can invoke a
message lambda, though.)</p>

<p>The syntax is <code>(mlambda <var>params</var> <var>body</var> <var>...</var>)</code>. <var>params</var> must be a
message which maps argument keys to symbols, or a signature (in which case the arguments will be matched to symbols
with the same names as the keys).  <var>body</var> begins a list of regular Scheme expressions.</p>

<p>For example, <code>(mlambda #msg(test . x a) <var>body</var> <var>...</var>)</code> will match any message with the
signature <code>#sig(test . x)</code>. When it matches, the value of <code>x</code> in the message will be bound
to <code>a</code>, and the <var>body</var> will be executed in that environment.</p>

<p><code>(mlambda #sig(test . x) <var>body</var> <var>...</var>)</code> will evaluate <var>body</var> in an
environment where the variable <code>x</code> is bound to the value of the <code>x</code> argument in the message.</p>

<p>See also <xref dest="messagesandsignatures"/>, <xref dest="func_objects"/>, and <xref dest="func_proc"/>.</p>

</section>

<section name="let"><title>Forms of Let</title>

<p>Sunlit World Scheme supports five let syntaxes. They all, except for <code>let <var>loop</var></code>, take the form
<code>(<var>let</var> <var>bindings</var> <var>body</var> <var>...</var>)</code>. The <var>let</var> keyword can be
<code>let</code>, <code>let*</code>, <code>letrec</code>, or <code>letrec*</code>.</p>

<p>The <var>bindings</var> is a list of zero or more bindings. Each binding is a list of the form
<code>(<var>var</var> <var>value</var>)</code>. The <var>value</var> is an expression that will be evaluated.</p>

<p>The <var>body</var>, which may consist of zero or more forms, is treated as a <code>begin</code>. Each expression
in <var>body</var> is evaluated in an extended environment where the variables are bound to the computed values.</p>

<ulp>

<li><code>let</code> evaluates all the <var>value</var> expressions first, then creates all the variables at
once. This means that the variables cannot refer to each other, but it also allows you to swap variables by doing
something like <code>(let ((x y) (y x)) <var>body</var>)</code>.</li>

<li><code>let*</code> evaluates the first <var>value</var> and then creates its variable. Then it evaluates the second
<var>value</var> in an environment where the first has already been defined, and creates its variable. Then it
evaluates the third in an environment where the first and second are defined, and so forth.</li>

<li><code>letrec</code> creates the variables first and then evaluates the <var>value</var> expressions in a context
where all the variables exist, but are uninitialized. Even though the variables are not initialized when the
<var>value</var> expressions are evaluated, the variables can still be referenced inside of a <code>lambda</code>
form. Then they can be initialized before the function is called. <code>letrec</code> is commonly used to define
mutually recursive functions.</li>

<li>Sunlit World Scheme&rsquo;s version of <code>letrec*</code> differs from the version defined in the forthcoming
R6RS standard. The Sunlit World Scheme version creates the first variable, then evaluates the first <var>value</var>
in an environment where the variable is defined but uninitialized. Then it creates the second variable, then evaluates
the second <var>value</var> in an environment where the first variable is initialized and the second is defined but
uninitialized. And so forth. This form allows you to define a series of recursive (but not mutually recursive)
functions.</li>

</ulp>

<p>There is a fifth form of let which is described in the next section.</p>

</section>

<section name="letloop"><title>Let Loop</title>

<p>The fifth form of let is <code>(let <var>loop</var> <var>bindings</var>
<var>body</var> <var>...</var>)</code>.</p>

<p><var>loop</var> can be any symbol. <code>let <var>loop</var></code> first evaluates the <var>value</var>s in the
<var>bindings</var>. Then it creates a variable called <var>loop</var> and leaves it uninitialized. Then it turns the
<var>body</var> into a procedure in a context where <var>loop</var> is defined and where the other <var>var</var>s in
the <var>bindings</var> are parameters. It stores the procedure in the variable <var>loop</var>, and calls it with the
<var>value</var>s as arguments.</p>

<p>The <var>loop</var> procedure can call itself with new arguments. This, combined with Scheme&rsquo;s use of proper
tail calls, makes iteration possible. However, the loop body is an ordinary procedure and can be called outside the
tail position, thus allowing it to be used for tree traversal or other forms of recursion.</p>

</section>

<section name="using"><title>Using</title>

<p>Sunlit World Scheme offers two alternatives to the forms of <code>let</code> which are designed for disposable
objects.</p>

<ulp>

<li><code>using</code> acts like <code>let</code>, but tracks the disposable objects that are assigned to the
variables, and runs <var>body</var> with a continuation that will dispose of all the disposable objects on the way
out. This disposal will occur if the <var>body</var> is exited with an exception or a normal return. However, this
syntax does not use <code>dynamic-wind</code> internally; it is possible to bypass the disposal by
using <code>call-with-current-continuation</code>.</li>

<li><code>using*</code> is to <code>using</code> what <code>let*</code> is to <code>let</code>. It allows each
variable to refer to the previous variable. It also assures that the disposals occur in the exact reverse order of
construction.</li>

</ulp>

</section>

<section name="match"><title>Old-Style Pattern Matching</title>

<p>This pattern-matching syntax in Sunlit World Scheme is an experimental, non-standard extension. It has been
replaced with <code>mcase</code> and will probably be removed in the future.</p>

<p>It looks like this: <code>(__match <var>expr</var> <var>clause</var>
<var>...</var>)</code></p>

<p>Each <var>clause</var> is of the form <code>(<var>pattern</var> <var>guard</var>
<var>body</var> <var>...</var>)</code>. The last <var>clause</var> may optionally take the
form <code>(else <var>body</var> <var>...</var>)</code>.</p>

<p>A <var>pattern</var> can be any of the following:</p>

<ulp>

<li><b>A pattern variable,</b> which is always a symbol beginning with <code>&lt;</code> and ending with
<code>&gt;</code>, such as <code>&lt;x&gt;</code> or even <code>&lt;&gt;</code>. A pattern variable matches
everything, and binds its match to the variable with the same name <i>including</i> the <code>&lt;</code> and
<code>&gt;</code>.</li>

<li><b>A symbol</b> (unless it looks like a pattern variable), which must match the input exactly.</li>

<li><b>A literal,</b> such as a boolean, integer, rational, floating-point number, character, or string, which must
match the input exactly.</li>

<li><b>A list,</b> which only matches a list. The list must match element-for-element. Really, a list consists of a
car and a cdr, so this is the same as saying that the car of the pattern must match the car of the data, and the cdr
of the pattern must match the cdr of the data. This means you can match a variable-length list by using a dotted list
and a pattern variable. The pattern <code>(begin . &lt;x&gt;)</code> would match any list starting with the symbol
<code>begin</code>.</li>

</ulp>

<p>First, <var>expr</var> is evaluated. Its value is matched against the <var>pattern</var> in the first
<var>clause</var>. If it matches, the pattern variables are bound and the <var>guard</var> is evaluated. If the
<var>guard</var> evaluates to non-<code>#f</code>, the <var>body</var> is evaluated in a context where the pattern
variables remain bound. Then <code>__match</code> returns the value of the last form of the <var>body</var>.</p>

<p>If a match against a <var>pattern</var> fails, or if it succeeds but then the <var>guard</var> returns
<code>#f</code>, <code>__match</code> attempts the next clause.</p>

<p>If the last clause fails, <code>__match</code> returns the unspecified value.</p>

<p>For example, here's a function that displaces a point: <code>(lambda (k) (__match k ((point &lt;x&gt; &lt;y&gt;) #t
`(point ,(+ &lt;x&gt; 1) ,(+ &lt;y&gt; 1))) (else #f)))</code>.</p>

</section>

<section name="catch"><title>Catch</title>

<p>The <code>catch</code> syntax can be used to catch dot-Net exceptions thrown by the implementation, or values that
are thrown using the <code>throw</code> function (see ahead).</p>

<p>The syntax is <code>(catch <var>handler</var> <var>body</var> <var>...</var>)</code>.</p>

<p>First, the <var>handler</var> expression is evaluated. This is expected to evaluate to a procedure that takes one
parameter.</p>

<p>Then, the <var>body</var> expressions are evaluated, in the manner of <code>begin</code>. (If there are no
<var>body</var> expressions, the unspecified value is returned.</p>

<p>If an exception is thrown during the evaluation of any <var>body</var> expression, evaluation stops and the
<var>handler</var> procedure is called, with the exception object itself as an argument. If the <var>handler</var>
itself throws an exception, then it must be caught by a higher <var>catch</var> clause.</p>

<p>If no exception is thrown, the value of the last <var>body</var> expression is returned.</p>

</section>

<section name="dynamicwind"><title>Dynamic Wind</title>

<p><code>dynamic-wind</code> (which rhymes with <i>find</i> and <i>mind</i>) allows you to set up what other languages
call a &ldquo;finally&rdquo; clause. However, because continuations can be used to leave and re-enter a function, it
is necessary to have a clause which is guaranteed to be executed on the way in as well as on the way out.</p>

<p>The syntax is <code>(dynamic-wind <var>pre</var> <var>body</var> <var>post</var>)</code>. Each of <var>pre</var>,
<var>body</var>, and <var>post</var> is supposed to be a single expression, although it can be a <code>(begin
<var>...</var>)</code> expression.</p>

<p><var>pre</var> is evaluated every time the <var>body</var> is entered. It is evaluated once, first, during ordinary
execution, and it is evaluated every time a continuation captured within the <var>body</var> is used to re-enter it
from outside.</p>

<p><var>post</var> is evaluated every time the <var>body</var> is exited. It is evaluated once, last, after the
evaluation of the <var>body</var>, and it is guaranteed to be evaluated if <var>body</var> throws an exception or
escapes through a previously-captured continuation.</p>

<p>If <var>body</var> captures and uses continuations internally, these continuations do not cause <var>pre</var> and
<var>post</var> to be invoked. Only transitions in and out of the <var>body</var> cause that.</p>

<p>If <var>pre</var> or <var>post</var> throws an exception, escapes through a continuation, or is re-entered through
a continuation, it does so in the context of <var>dynamic-wind</var>, not in the context created for
<var>body</var>. Note that a continuation captured during a <var>pre</var> or <var>post</var> will, if called again,
attempt to continue the operation that cause <var>pre</var> or <var>post</var> to run in the first place.</p>

<p>Barring exceptions or continuations, <var>body</var> is evaluated normally and, after <var>post</var> is run, the
value of <var>body</var> is returned.</p>

</section>

</section>

<section name="functions"><title>Functions</title>

<p>Sunlit World Scheme provides a large collection of functions for various uses.</p>

<p>Functions are written here the way you would use them when you first start Scheme.</p>

<section name="func_math"><title>Math Functions</title>

<p>These math functions work on all numeric types. An exact result will be returned as either an integer or a
rational. An inexact result will be returned as a float. The result will be exact if all arguments are exact.</p>

<ulp>

<li><code>(+ <var>number</var> <var>...</var>)</code>. Adds numbers. This function can also be used to add 3-D vectors,
but numbers and 3-D vectors cannot be added to each other. A 3-D vertex can also be added to a set of 3-D vectors.</li>

<li><code>(- <var>number</var>)</code>. Negates a number or a 3-D vector.</li>

<li><code>(- <var>minuend</var> <var>subtrahend</var> <var>...</var>)</code>. Subtracts each <var>subtrahend</var>
from the <var>minuend</var>. This function can also be used to subtract 3-D vectors, but numbers and 3-D vectors
cannot be subtracted from each other. A vector can be subtracted from a 3-D vertex, yielding another vertex. A vertex
can also be subtracted from another vertex, yielding the displacement from the <var>subtrahend</var> to
the <var>minuend</var>.</li>

<li><code>(* <var>factor</var> <var>...</var>)</code>. Multiplies numbers. This function can also be used to multiply
a 3-D vector by one or more scalars; the 3-D vector can appear anywhere in the list of arguments, but there can be
only one.</li>

<li><code>(/ <var>number</var>)</code>. Finds the reciprocal of a number.</li>

<li><code>(/ <var>dividend</var> <var>divisor</var> <var>...</var>)</code>. Divides the <var>dividend</var> by each
<var>divisor</var>. This function can also be used to divide a 3-D vector by one or more scalars. The 3-D vector must
come first in the list of arguments.</li>

<li><code>(min <var>number</var> <var>...</var>)</code>. Finds the minimum of all the numbers.</li>

<li><code>(max <var>number</var> <var>...</var>)</code>. Finds the maximum of all the numbers.</li>

</ulp>

<p>The following functions only work on exact integers and rationals.</p>

<ulp>

<li><code>(gcd <var>number</var> <var>...</var>)</code>. Finds the greatest common divisor of all the numbers.</li>

<li><code>(lcm <var>number</var> <var>...</var>)</code>. Finds the least common multiple of all the numbers.</li>

</ulp>

<p>Scheme supports two types of signed division, <i>symmetric</i> and <i>floored.</i> Both yield the same results as
unsigned division when the inputs are positive. Symmetric division is equivalent to taking the absolute values of the
inputs, doing an unsigned division, then calculating what the signs should be. In symmetric division, <code>-1</code>
divided by <code>1000</code> is <code>0</code> remainder <code>-1</code>. Floored division is equivalent to adding a
sufficiently large multiple of the divisor to the dividend that both have the same sign, then doing the division, then
subtracting the multiplier that was used from the quotient. In floored division, <code>-1</code> divided
by <code>1000</code> is <code>-1</code> remainder <code>999</code>. Symmetric division is symmetric about
zero. Floored division does not treat zero specially, and therefore is well-suited for applications where the location
of zero is chosen arbitrarily.</p>

<ulp>

<li><code>(quotient <var>dividend</var> <var>divisor</var>)</code>. Finds the integer portion of <var>dividend</var>
divided by <var>divisor</var>, using symmetric division. (If you want floored division, use <code>(floor (/
<var>dividend</var> <var>divisor</var>))</code>.)</li>

<li><code>(remainder <var>dividend</var> <var>divisor</var>)</code>. Finds the remainder of <var>dividend</var>
divided by <var>divisor</var>, using symmetric division.</li>

<li><code>(modulo <var>dividend</var> <var>divisor</var>)</code>. Finds the remainder of <var>dividend</var> divided
by <var>divisor</var>, using floored division.</li>

</ulp>

<p>The following functions are used to convert between integers and strings. Any integer base from <code>2</code>
to <code>36</code> is supported.</p>

<ulp>

<li><code>(bigint-&gt;string <var>int</var> <var>base</var>)</code>. Converts the integer <var>int</var> to a string
of digits in base <var>base</var>. The <var>base</var> must be an integer from <code>2</code> to <code>36</code>. If
<var>int</var> is negative, the string will have a leading minus sign.</li>

<li><code>(string-&gt;bigint <var>str</var> <var>base</var>)</code>. Interprets the string <var>str</var> as an
integer in base <var>base</var>. The <var>base</var> must be an integer from <code>2</code> to <code>36</code>. If
<var>str</var> has a leading minus sign, the integer will be negative.</li>

</ulp>

<p>The following functions help with rational numbers.</p>

<ulp>

<li><code>(make-rational <var>numerator</var> <var>denominator</var>)</code>. Makes a rational number with the given
<var>numerator</var> and <var>denominator</var>.</li>

<li><code>(numerator <var>frac</var>)</code>. Returns the numerator of the rational number <code>frac</code>.</li>

<li><code>(denominator <var>frac</var>)</code>. Returns the denominator of the rational number <code>frac</code>.</li>

</ulp>

<p>The following functions can round rationals or floating-point numbers.</p>

<ulp>

<li><code>(floor <var>num</var>)</code>. Returns the greatest integer not greater than <var>num</var>.</li>

<li><code>(ceiling <var>num</var>)</code>. Returns the least integer not less than <var>num</var>.</li>

<li><code>(round <var>num</var>)</code>. Returns the nearest integer to <var>num</var>. If there is an exact tie,
returns the even integer.</li>

<li><code>(truncate <var>num</var>)</code>. Returns the integer closest to <var>num</var> whose absolute value is not
greater than the absolute value of <var>num</var>. In other words, rounds toward zero.</li>

</ulp>

<p>The following functions and variables are available only for floating-point numbers.</p>

<ul>

<li><code>pi</code>. This variable contains the value of the mathematical constant &#x3c0;.</li>

<li><code>e</code>. This variable contains the value of the mathematical constant e.</li>

<li><code>(acos <var>r</var>)</code>. Inverse cosine.</li>

<li><code>(asin <var>r</var>)</code>. Inverse sine.</li>

<li><code>(atan <var>r</var>)</code>. Inverse tangent.</li>

<li><code>(atan2 <var>y</var> <var>x</var>)</code>. Inverse tangent with two components.</li>

<li><code>(cos <var>a</var>)</code>. Cosine.</li>

<li><code>(cosh <var>a</var>)</code>. Hyperbolic cosine.</li>

<li><code>(exp <var>n</var>)</code>. Exponent. Raises the constant e to the power of <var>n</var>.</li>

<li><code>(log <var>n</var>)</code>. Natural logarithm.</li>

<li><code>(log10 <var>n</var>)</code>. Common logarithm.</li>

<li><code>(sin <var>a</var>)</code>. Sine.</li>

<li><code>(sinh <var>a</var>)</code>. Hyperbolic sine.</li>

<li><code>(sqrt <var>n</var>)</code>. Square root.</li>

<li><code>(tan <var>a</var>)</code>. Tangent.</li>

<li><code>(tanh <var>a</var>)</code>. Hyperbolic tangent.</li>

</ul>

</section>

<section name="func_compare"><title>Comparison and Logic Functions</title>

<p>In spite of the notation, each comparison operator requires two or more arguments.</p>

<ulp>

<li><code>(&lt; <var>number</var> <var>...</var>)</code>. Returns <code>#t</code> if the numbers are increasing (each
number less than the next), otherwise returns <code>#f</code>.</li>

<li><code>(&lt;= <var>number</var> <var>...</var>)</code>. Returns <code>#t</code> if the numbers are nondecreasing
(each number less than or equal to the next), otherwise returns <code>#f</code>.</li>

<li><code>(&gt;= <var>number</var> <var>...</var>)</code>. Returns <code>#t</code> if the numbers are nonincreasing
(each number greater than or equal to the next), otherwise returns <code>#f</code>.</li>

<li><code>(&gt; <var>number</var> <var>...</var>)</code>. Returns <code>#t</code> if the numbers are decreasing (each
number greater than the next), otherwise returns <code>#f</code>.</li>

<li><code>(boolean? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is <code>#t</code>
or <code>#f</code>, and <code>#f</code> otherwise.</li>

<li><code>(not <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is <code>#f</code>,
and <code>#f</code> otherwise.</li>

</ulp>

</section>

<section name="func_bitwise"><title>Bitwise Logic Functions on Integers</title>

<p>These functions are important enough to deserve their own section.</p>

<p>A positive integer has an infinite number of leading zeros; a negative integer has an infinite number of leading
ones.</p>

<ulp>

<li><code>(logand <var>a</var> <var>...</var>)</code>. Finds the logical and of zero or more integers. If no integers
are provided, this function returns <code>-1</code>, which is the identity under logical and. If one integer is
provided, it is returned. If two or more integers are provided, an integer is returned which has bits set only in
those positions where all the input integers have bits set.</li>

<li><code>(logior <var>a</var> <var>...</var>)</code>. Finds the logical or of zero or more integers. If no integers
are provided, this function returns <code>0</code>, which is the identity under logical or. If one integer is
provided, it is returned. If two or more integers are provided, an integer is returned which has bits set wherever any
of the integers has a bit set.</li>

<li><code>(logxor <var>a</var> <var>...</var>)</code>. Finds the logical xor of zero or more integers. If no integers
are provided, this function returns <code>0</code>, which is the identity under logical xor. If one integer is
provided, it is returned. If two or more integers are provided, an integer is returned which has bits set wherever an
odd number of the input integers has a bit set.</li>

<li><code>(lognot <var>a</var>)</code>. Finds the logical complement of an integer.</li>

<li><code>(shl <var>a</var> <var>b</var>)</code>. Shifts <var>a</var> to the left <var>b</var> places, shifting zeros
in on the right. If <var>b</var> is negative, a right shift occurs.</li>

<li><code>(shr <var>a</var> <var>b</var>)</code>. Shifts <var>a</var> to the right <var>b</var> places. If
<var>b</var> is negative, a left shift occurs, shifting in zeros on the right.</li>

<li><code>(shl1 <var>a</var> <var>b</var>)</code>. Shifts <var>a</var> to the left <var>b</var> places, shifting ones
in on the right. If <var>b</var> is negative, a right shift occurs.</li>

<li><code>(shr1 <var>a</var> <var>b</var>)</code>. Shifts <var>a</var> to the right <var>b</var> places. If
<var>b</var> is negative, a left shift occurs, shifting in ones on the right.</li>

<li><code>(lsb <var>a</var>)</code>. Returns the position of the most significant bit that differs from the sign
bit. If <var>a</var> is <code>0</code> or <code>-1</code>, it is all sign bits, and <code>-1</code> is returned.</li>

</ulp>

</section>

<section name="geometry"><title>3-D Geometry Functions</title>

<p>These functions work with 3-D vectors, vertices, lines, and planes.</p>

<p>The coordinate system is right-handed. A right-handed coordinate system can be rotated such that X is east, Y
is north, and Z is up.</p>

<p>Since the geometry functions use exact rational numbers instead of floating-point numbers, they are all exact.</p>

<ulp>

<li><code>(vector3? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a 3-D vector, otherwise
returns <code>#f</code>.</li>

<li><code>(make-vector3 <var>x</var> <var>y</var> <var>z</var>)</code>. Makes a new 3-D vector from its three
cartesian components. The components must be integers or rational numbers.</li>

<li><code>(vector3-x <var>vec3</var>)</code>. Returns the X component of the 3-D vector <var>vec3</var>.</li>

<li><code>(vector3-y <var>vec3</var>)</code>. Returns the Y component of the 3-D vector <var>vec3</var>.</li>

<li><code>(vector3-z <var>vec3</var>)</code>. Returns the Z component of the 3-D vector <var>vec3</var>.</li>

<li><code>(vector3-zero? <var>vec3</var>)</code>. Returns <code>#t</code> if <var>vec3</var> is the zero
vector, and <code>#f</code> otherwise.</li>

<li><code>(vertex3? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a 3-D vertex,
and <code>#f</code> otherwise.</li>

<li><code>(vertex3-x <var>vtx3</var>)</code>. Returns the X position of the 3-D vertex <var>vtx3</var>.</li>

<li><code>(vertex3-y <var>vtx3</var>)</code>. Returns the Y position of the 3-D vertex <var>vtx3</var>.</li>

<li><code>(vertex3-z <var>vtx3</var>)</code>. Returns the Z position of the 3-D vertex <var>vtx3</var>.</li>

<li><code>(dot <var>vec3a</var> <var>vec3b</var>)</code>. Returns the dot product of the two 3-D vectors
<var>vec3a</var> and <var>vec3b</var>.</li>

<li><code>(cross <var>vec3a</var> <var>vec3b</var>)</code>. Returns the cross product of the two 3-D vectors
<var>vec3a</var> and <var>vec3b</var>.</li>

<li><code>(vector3-length-squared <var>vec3</var>)</code>. Returns the square of the length of the 3-D vector
<var>vec3</var>. (This is the same as the dot product of <var>vec3</var> with itself.)</li>

<li><code>(vector3-scaled-length-along <var>vec3</var> <var>vec3axis</var>)</code>. Returns the length of the
component of <var>vec3</var> parallel to <var>vec3axis</var>, divided by the length of <var>vec3axis</var>. (This
number is guaranteed to be rational and can be calculated without the use of square roots.)</li>

<li><code>(vector3-component-along <var>vec3</var> <var>vec3axis</var>)</code>. Finds the component of <var>vec3</var>
which is parallel to <var>vec3axis</var>.</li>

<li><code>(vector3-component-ortho <var>vec3</var> <var>vec3axis</var>)</code>. Finds the component of
<var>vec3</var> which is perpendicular to <var>vec3axis</var>. The sum of the components of <var>v</var> parallel and
perpendicular to an axis <var>a</var> will equal <var>v</var>.</li>

<li><code>(interpolate <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var> <var>x3</var>)</code>. Finds <var>y3</var>
such that the points <code>(<var>x1</var>, <var>y1</var>)</code>, <code>(<var>x2</var>, <var>y2</var>)</code>, and
<code>(<var>x3</var>, <var>y3</var>)</code> are colinear. This function also works if the <var>y</var> values are 3-D
vectors or 3-D vertices. This function produces a division by zero if <var>x2</var> and <var>x1</var> are the
same.</li>

<li><code>(line3? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a 3-D line, otherwise
returns <code>#f</code>. 3-D lines are infinite in length.</li>

<li><code>(make-line3-origin-direction <var>origin</var> <var>direction</var>)</code>. <var>origin</var> must be a
vertex and <var>direction</var> must be a vector. Creates and returns a new line passing through <var>origin</var> and
oriented in the direction of <var>direction</var>.</li>

<li><code>(make-line3-two-points <var>p1</var> <var>p2</var>)</code>. <var>p1</var> and <var>p2</var> must be
vertices. Creates and returns a new line passing through both points.</li>

<li><code>(line3-origin <var>line3</var>)</code>. Returns a vertex denoting the origin of <var>line3</var>.</li>

<li><code>(line3-direction <var>line3</var>)</code>. Returns a vector denoting the direction of <var>line3</var>.</li>

<li><code>(plane3? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a 3-D plane, otherwise
returns <code>#f</code>. 3-D planes are infinite in area.</li>

<li><code>(make-plane3-origin-normal <var>origin</var> <var>normal</var>)</code>. Creates and returns a new 3-D plane
which passes through the vertex <var>origin</var> and is perpendicular to the normal vector <var>normal</var>.</li>

<li><code>(make-plane3-two-points <var>p1</var> <var>p2</var>)</code>. Creates and returns a new 3-D plane which
passes through <var>p1</var> and faces directly toward <var>p2</var>. The plane will be perpendicular to the line
passing through <var>p1</var> and <var>p2</var>.</li>

<li><code>(make-plane3-three-points <var>p1</var> <var>p2</var> <var>p3</var>)</code>. Creates and returns a new 3-D
plane which passes through the three points. The points must be non-colinear. Seen from the front, the angle
around <var>p1</var> from <var>p2</var> to <var>p3</var> will be counter-clockwise.</li>

<li><code>(make-plane3-four-points <var>p1</var> <var>p2</var> <var>p3</var> <var>p4</var>)</code>. Creates and
returns a new 3-D plane which passes through <var>p1</var>, <var>p2</var>, and <var>p3</var>, and faces away from
(&ldquo;includes&rdquo;) <var>p4</var>. <var>p4</var> must not lie in the plane.</li>

<li><code>(plane3-origin <var>plane3</var>)</code>. Returns the origin vertex of the 3-D plane <var>plane3</var>.</li>

<li><code>(plane3-normal <var>plane3</var>)</code>. Returns a vector perpendicular to the 3-D plane <var>plane3</var>,
which points in the direction the plane is facing.</li>

<li><code>(plane3-excludes? <var>plane</var> <var>vertex</var>)</code>. Returns <code>#t</code> if <var>vertex</var>
is in front of <var>plane</var> (as defined by <var>plane</var>&rsquo;s normal pointing &ldquo;forward&rdquo;),
or <code>#f</code> if <var>plane</var> contains <var>vertex</var> or if <var>vertex</var> is
behind <var>plane</var>.</li>

<li><code>(plane3-includes? <var>plane</var> <var>vertex</var>)</code>. Returns <code>#t</code> if <var>vertex</var>
is behind <var>plane</var> or <code>#f</code> if <var>plane</var> contains <var>vertex</var> or if <var>vertex</var>
is in front of <var>plane</var>.</li>

<li><code>(plane3-flip <var>plane3</var>)</code>. Returns a plane coincident with <var>plane3</var> but facing in the
opposite direction.</li>

<li><code>(plane3-flip-to-include <var>plane3</var> <var>vertex</var>)</code>. Returns a plane coincident
with <var>plane3</var> but facing away from (&ldquo;including&rdquo;) <var>vertex</var>.</li>

<li><code>(coincident? <var>obj1</var> <var>obj2</var>)</code>. <var>obj1</var> and <var>obj2</var> must each be a
vertex, a line, or a plane. Returns <code>#t</code> if two vertices are the same, if two lines are coincident, if two
planes are coincident, if a vertex lies inside a line, if a vertex lies inside a plane, or if a line lies entirely
within a plane. Returns <code>#f</code> otherwise.</li>

<li><code>(parallel? <var>obj1</var> <var>obj2</var>)</code>. Returns <code>#t</code> if two objects, each of which
can be a vector, a line, or a plane, are parallel, and <code>#f</code> otherwise. Coincident objects are considered
parallel.</li>

<li><code>(skew? <var>obj1</var> <var>obj2</var>)</code>. <var>obj1</var> and <var>obj2</var> must each be a line or a
plane. Returns <code>#f</code> if either one is a plane. If the two are lines that do not lie in the same plane,
returns <code>#t</code>, otherwise, if the lines are parallel or intersecting, returns <code>#f</code>.</li>

<li><code>(intersecting? <var>obj1</var> <var>obj2</var>)</code>. <var>obj1</var> and <var>obj2</var> must each be a
line or plane. Returns <code>#t</code> if the objects intersect and <code>#f</code> if they are coincident, parallel,
or skew.</li>

<li><code>(perpendicular? <var>obj1</var> <var>obj2</var>)</code>. <var>obj1</var> and <var>obj2</var> must each be a
3-D vector, line, or plane. Returns <code>#t</code> if the objects are perpendicular (which implies they are either
intersecting or, in the case of lines, skew), and <code>#f</code> otherwise.</li>

<li><code>(intersection <var>obj1</var> <var>obj2</var>)</code>. Each of <var>obj1</var> and <var>obj2</var> can be a
line or a plane. Returns the intersection of the two objects or one of the
symbols <code>coincident</code>, <code>parallel</code>, or, for two lines, <code>skew</code>. If two planes are given
as arguments, the intersection is a line, otherwise, the intersection is a vertex.</li>

<li><code>(nearest-point <var>obj</var> <var>pt</var>)</code>. <var>obj</var> must be a line or a plane. Finds the
point on <var>obj</var> nearest to <var>pt</var>.</li>

<li><code>convex-hull-empty</code>. This variable contains an empty convex hull.</li>

<li><code>(convex-hull? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a convex hull,
and <code>#f</code> otherwise.</li>

<li><code>(convex-hull-add <var>hull</var> <var>vertex</var>)</code>. Adds <var>vertex</var> to the convex
hull <var>hull</var> and returns either a new convex hull (if <var>vertex</var> falls outside <var>hull</var>)
or <var>hull</var> (if <var>vertex</var> falls inside <var>hull</var> or on one of its corners, edges, or faces).</li>

<li><code>(convex-hull-point-status <var>hull</var> <var>vertex</var>)</code>. Determines where <var>vertex</var>
falls with respect to the convex hull <var>hull</var>. Returns one of the
symbols <code>outside</code>, <code>oncorner</code>, <code>onedge</code>, <code>onface</code>,
or <code>inside</code>.</li>

</ulp>

</section>

<section name="func_lists"><title>List Functions</title>

<p>These are the list primitives.</p>

<ulp>

<li><code>(null? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is the empty list;
otherwise returns <code>#f</code>.</li>

<li><code>(pair? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is a reference to a
cons cell; otherwise returns <code>#f</code>.</li>

<li><code>(car <var>pair</var>)</code>. Returns the car field of a cons cell.</li>

<li><code>(cdr <var>pair</var>)</code>. Returns the cdr field of a cons cell.</li>

<li><code>(cons <var>car</var> <var>cdr</var>)</code>. Allocates a new cons cell and sets its car and cdr fields to
the given values.</li>

<li><code>(set-car! <var>pair</var> <var>value</var>)</code>. Sets the car field of <var>pair</var> to
<var>value</var>.</li>

<li><code>(set-cdr! <var>pair</var> <var>value</var>)</code>. Sets the cdr field of <var>pair</var> to
<var>value</var>.</li>

</ulp>

<p>Standard Scheme defines a number of helper procedures that compose the <code>car</code> and <code>cdr</code>
primitives in various ways. Sunlit World Scheme supports them out to four levels.</p>

<ulp>

<li><code>(caar <var>pair</var>)</code>. Same as <code>(car (car <var>pair</var>))</code>.</li>

<li><code>(cadr <var>pair</var>)</code>. Same as <code>(car (cdr <var>pair</var>))</code>.</li>

<li><code>(cdar <var>pair</var>)</code>. Same as <code>(cdr (car <var>pair</var>))</code>.</li>

<li>...</li>

<li><code>(cddddr <var>pair</var>)</code>. Same as <code>(cdr (cdr (cdr (cdr <var>pair</var>))))</code>.</li>

</ulp>

<p>In order to make it easier to work with nested list structures, Sunlit World Scheme offers these functions, which
check whether the helper procedures or the primitives will succeed. These are also defined out to four levels.</p>

<ulp>

<li><code>(car? <var>obj</var>)</code>. Returns <code>#t</code> if <code>(car <var>obj</var>)</code> is possible (i.e,
returns <code>#t</code> if <var>obj</var> is a pair), otherwise returns <code>#f</code>.</li>

<li><code>(cdr? <var>obj</var>)</code>. Returns <code>#t</code> if <code>(cdr <var>obj</var>)</code> is possible,
otherwise returns <code>#f</code>.</li>

<li><code>(caar? <var>obj</var>)</code>. Returns <code>#t</code> if <code>(caar <var>obj</var>)</code> is possible
(i.e., <code>(caar? <var>obj</var>)</code> is equivalent to <code>(and (pair? <var>obj</var>) (pair?
(car <var>obj</var>)))</code>), otherwise returns <code>#f</code>.</li>

<li>...</li>

<li><code>(cddddr? <var>obj</var>)</code>. Returns <code>#t</code> if <code>(cddddr <var>obj</var>)</code> is
possible, otherwise returns <code>#f</code>.</li>

</ulp>

<p>The following functions do general list processing.</p>

<ulp>

<li><code>(list? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a proper list, which can be
traversed without cycles and ends with the empty list. Otherwise returns <code>#f</code>.</li>

<li><code>(length <var>list</var>)</code>. Counts the number of items in the proper list <var>list</var>. This
requires stepping down the list one item at a time. If given a cyclic list, may loop forever.</li>

<li><code>(length-up-to <var>limit</var> <var>list</var>)</code>. Counts the number of items in the list
<var>list</var>, but stops upon reaching <var>limit</var>. This makes it possible to verify that <var>list</var> has
some minimum number of elements without taking a long time if <var>list</var> turns out to have a great many more
elements than the minimum. If given a cyclic list, <code>length-up-to</code> will return <var>limit</var>.</li>

<li><code>(list-copy <var>list</var>)</code>. Allocates a new copy of <var>list</var>.</li>

<li><code>(reverse-copy <var>list</var>)</code>. Returns a new copy of <var>list</var> with the items reversed.</li>

<li><code>(list-&gt;vector <var>list</var>)</code>. Converts a list to a vector.</li>

<li><code>(list <var>item</var> <var>...</var>)</code>. Creates a list with the given items.</li>

<li><code>(apply <var>func</var> <var>arg</var> <var>...</var> <var>arglist</var>)</code>. Populates a list with the
<var>arg</var>s, appends the list <var>arglist</var>, then calls <var>func</var> with those list items as
arguments.</li>

<li><code>(map <var>func</var> <var>list</var> <var>...</var>)</code>. All the <var>list</var>s are expected to be the
same length. Calls <var>func</var> with the first items from each list as parameters, then with the second items from
each list, and so forth. Collects the return values of <var>func</var> into a list and returns that list. Thus,
<code>(map (lambda (x) (* x x)) '(1 2 3 4 5))</code> evaluates to <code>(1 4 9 16 25)</code>.</li>

<li><code>(iota <var>start</var> <var>end</var>)</code>. If <var>start</var> is less than <var>end</var>, returns a
new list containing all the integers, in ascending order, less than <var>end</var> but not less
than <var>start</var>. If <var>end</var> is less than <var>start</var>, returns a new list containing all the
integers, in descending order, less than <var>start</var> but not less than <var>end</var>. If <var>start</var>
and <var>end</var> are equal, returns the empty list.</li>

<li><code>(append <var>list1</var> <var>...</var>)</code>. Returns a new list containing all the items of all the
lists in order.</li>

<li><code>(collect <var>func</var> <var>list</var> <var>...</var>)</code>. Same as <code>map</code> except that the
results of <var>func</var> are expected to be (possibly empty) lists and are concatenated.</li>

<li><code>(for-each <var>func</var> <var>list</var> <var>...</var>)</code>. Same as <code>map</code> but returns the
unspecified value. The return values of <var>func</var> are all discarded.</li>

<li><code>(filter <var>func</var> <var>list</var>)</code>. Returns a new list containing only the items
in <var>list</var> for which <var>func</var> returns <code>#t</code>.</li>

<li><code>(fold <var>func</var> <var>initial-state</var> <var>list</var>)</code>. If <var>list</var> is empty,
returns <var>initial-state</var>, otherwise returns the result of <code>(fold <var>func</var>
(<var>func</var> <var>initial-state</var> (car <var>list</var>)) (cdr <var>list</var>))</code>.</li>

<li><code>(sort <var>less-than</var> <var>list</var>)</code>. Sorts the items in <var>list</var> according to the
given <var>less-than</var> function. The <var>less-than</var> function must accept two parameters (which will always
be items taken from the list) and must return a boolean. In Sunlit World Scheme, <code>sort</code> is a stable sort
and operates in time proportional to <code>(let* ((N (length <var>list</var>))) (* N (log N)))</code>.
It employs mutable state internally, and thus may behave incorrectly if <var>less-than</var> returns more than once
through a captured continuation.</li>

<li><code>(merge <var>less-than</var> <var>list1</var> <var>list2</var>)</code>. Merges the items in the two sorted
lists <var>list1</var> and <var>list2</var> according to the given <var>less-than</var> function. This is a stable
merge and operates in linear time. If the lists are not sorted properly, the result will not be sorted properly
either.</li>

<li><code>(shuffle <var>random</var> <var>list</var>)</code>. Returns a copy of <var>list</var> with the elements in
random order. <var>random</var> is the random number generator to use. If <var>i</var> is a positive
integer, <code>(<var>random</var> <var>i</var>)</code> should return an integer less than <var>i</var> but not less
than zero. The built-in function <code>random-int</code> is suitable if cryptography-grade randomness is not
needed.</li>

</ulp>

</section>

<section name="func_strings"><title>String Functions</title>

<ulp>

<li><code>(make-string <var>len</var> <var>ch</var>)</code>. Returns a string of <var>len</var> copies of the
character <var>ch</var>. <var>len</var> must be an integer.</li>

<li><code>(string? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a string, and <code>#f</code>
otherwise.</li>

<li><code>(string-length <var>str</var>)</code>. Returns the length of the string <var>str</var>.</li>

<li><code>(string-ref <var>str</var> <var>i</var>)</code>. Returns the character of the string <var>str</var> at index
<var>i</var>.</li>

<li><code>(string-set! <var>str</var> <var>i</var> <var>ch</var>)</code>. Sets the character of the string
<var>str</var> at index <var>i</var> to <var>ch</var>.</li>

<li><code>(string-copy! <var>src</var> <var>srcoff</var> <var>len</var> <var>dest</var> <var>destoff</var>)</code>
Copies <var>len</var> characters from the string <var>src</var> at offset <var>srcoff</var> to the string
<var>dest</var> at offset <var>destoff</var>.</li>

<li><code>(string-fill! <var>dest</var> <var>destoff</var> <var>len</var> <var>ch</var>)</code>. Fills <var>len</var>
characters of the string <var>dest</var>, starting at the offset <var>destoff</var>, with the character
<var>ch</var>.</li>

<li><code>(substring <var>str</var> <var>off</var> <var>len</var>)</code>. Returns a new string consisting of a copy
of the <var>len</var> characters in the string <var>str</var> starting at offset <var>off</var>.</li>

<li><code>(string&lt;? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings are strictly
ascending and <code>#f</code> otherwise. Comparison is case-sensitive.</li>

<li><code>(string&gt;? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings are
strictly descending and <code>#f</code> otherwise.</li>

<li><code>(string&lt;=? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings are non-descending
and <code>#f</code> otherwise.</li>

<li><code>(string&gt;=? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings are non-ascending
and <code>#f</code> otherwise.</li>

<li><code>(string=? <var>str1</var> <var>str2</var>)</code>. Returns <code>#t</code> if the two strings have equal values,
and <code>#f</code> otherwise.</li>

<li><code>(string!=? <var>str1</var> <var>str2</var>)</code>. Returns <code>#t</code> if the two strings have
different values, and <code>#f</code> otherwise.</li>

<li><code>(string-ci&lt;? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings, ignoring
case, are strictly ascending, and <code>#f</code> otherwise.</li>

<li><code>(string-ci&gt;? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings, ignoring
case, are strictly descending, and <code>#f</code> otherwise.</li>

<li><code>(string-ci&lt;=? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings, ignoring
case, are non-ascending, and <code>#f</code> otherwise.</li>

<li><code>(string-ci&gt;=? <var>str1</var> <var>...</var>)</code>. Returns <code>#t</code> if the strings, ignoring
case, are non-descending, and <code>#f</code> otherwise.</li>

<li><code>(string-ci=? <var>str1</var> <var>str2</var>)</code>. Returns <code>#t</code> if the strings, ignoring case,
have equal values, and <code>#f</code> otherwise.</li>

<li><code>(string-ci!=? <var>str1</var> <var>str2</var>)</code>. Returns <code>#t</code> if the strings, ignoring
case, have different values, and <code>#f</code> otherwise.</li>

</ulp>

</section>

<section name="func_vectors"><title>Vector Functions</title>

<p>Vectors in Sunlit World Scheme are actually deques.</p>
<ulp>

<li><code>(make-vector <var>len</var> <var>obj</var>)</code>. Returns a newly allocated vector of length
<var>len</var>, where each item is the object <var>obj</var>.</li>

<li><code>(vector <var>obj</var> <var>...</var>)</code>. Returns a newly allocated vector with the given
elements as contents.</li>

<li><code>(vector? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a vector, and <code>#f</code>
otherwise.</li>

<li><code>(vector-length <var>vec</var>)</code>. Returns the length of vector <var>vec</var>.</li>

<li><code>(vector-ref <var>vec</var> <var>i</var>)</code>. Returns the element of <var>vec</var> at index
<var>i</var>.</li>

<li><code>(vector-set! <var>vec</var> <var>i</var> <var>value</var>)</code>. Sets the element of <var>vec</var> at
index <var>i</var> to <var>value</var>.</li>

<li><code>(vector-push-front! <var>vector</var> <var>obj</var>)</code>. Appends <var>obj</var> to the beginning of
the vector <var>vector</var>. This modifies <var>vector</var>, increasing its size by one.</li>

<li><code>(vector-push-back! <var>vector</var> <var>obj</var>)</code>. Appends <var>obj</var> to the end of the
vector <var>vector</var>. This modifies <var>vector</var>, increasing its size by one.</li>

<li><code>(vector-pop-front! <var>vector</var>)</code>. Removes the first item from the vector <var>vector</var>
and returns it. This modifies <var>vector</var>, reducing its size by one.</li>

<li><code>(vector-pop-back! <var>vector</var>)</code>. Removes the last item from the vector <var>vector</var>
and returns it. This modifies <var>vector</var>, reducing its size by one.</li>

<li><code>(vector-copy! <var>src</var> <var>srcoff</var> <var>len</var> <var>dest</var>
<var>destoff</var>)</code>. Copies <var>len</var> elements from the vector <var>src</var> starting at index
<var>srcoff</var> to the vector <var>dest</var> starting at element <var>destoff</var>.</li>

<li><code>(vector-fill! <var>dest</var> <var>destoff</var> <var>len</var> <var>obj</var>)</code>. Sets <var>len</var>
elements of the vector <var>dest</var>, starting at index <var>destoff</var>, to the value <var>obj</var>.</li>

<li><code>(vector-shuffle! <var>random</var> <var>vec</var>)</code>. Shuffles the elements in <var>vec</var> using
the random function <var>random</var>. <var>vec</var> is modified in place.</li>

</ulp>

</section>

<section name="hashset"><title>Functions for Hash-Based Data Structures</title>

<p>These functions are used for basic hashing.</p>

<ulp>

<li><code>(hashable? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is hashable and <code>#f</code>
if it is not.</li>

<li><code>(hash-bytes <var>bytearray</var> <var>off</var> <var>len</var>)</code>. Returns the hash of the given part
of the byte array <var>bytearray</var>.</li>

<li><code>(hash <var>obj</var>)</code>. Returns the hash of the object <var>obj</var>, which must be hashable or an
exception is thrown.</li>

</ulp>

<p>These functions allow access to hash sets.</p>

<ulp>

<li><code>(make-hashset <var>obj</var> <var>...</var>)</code>. Returns a new hash set containing the given objects,
which must all be hashable.</li>

<li><code>(hashset? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a hash set, and <code>#f</code>
otherwise.</li>

<li><code>(hashset-length <var>hashset</var>)</code>. Returns the number of items in <var>hashset</var>.</li>

<li><code>(hashset-contains? <var>hashset</var> <var>obj</var>)</code>. Returns <code>#t</code> if <var>hashset</var>
contains <var>obj</var>, and <code>#f</code> otherwise. An exception is thrown if <var>obj</var> is not hashable.</li>

<li><code>(hashset-add! <var>hashset</var> <var>obj</var>)</code>. Adds <var>obj</var> to <var>hashset</var>. This
destructively modifies <var>hashset</var>. <var>obj</var> must be hashable or an exception is thrown. This function
does nothing if <var>obj</var> is already in <var>hashset</var>.</li>

<li><code>(hashset-remove! <var>hashset</var> <var>obj</var>)</code>. Removes <var>obj</var> from <var>hashset</var>.
This destructively modifies <var>hashset</var>. <var>obj</var> must be hashable or an exception is thrown. This
function does nothing if <var>obj</var> is not found in <var>hashset</var>.</li>

<li><code>(hashset-&gt;list <var>hashset</var>)</code>. Returns a list of all the items in <var>hashset</var>.</li>

<li><code>(hashset-&gt;vector <var>hashset</var>)</code>. Returns a vector of all the items in <var>hashset</var>.</li>

<li><code>(hashset-union <var>h1</var> <var>h2</var> <var>...</var>)</code>. Returns the union of the given hash sets.</li>

<li><code>(hashset-intersection <var>h1</var> <var>h2</var> <var>...</var>)</code>. Returns the intersection of the given
hash sets.</li>

<li><code>(hashset-difference <var>h1</var> <var>h2</var> <var>...</var>)</code>. Finds the union of all the hash sets
except <var>h1</var>, then returns the hash set of all the items that are in <var>h1</var> but are not in that union.</li>

<li><code>(hashset-symmetric-difference <var>h1</var> <var>h2</var> <var>...</var>)</code>. Finds all the items that are
in an odd number of the hash sets provided as arguments.</li>

</ulp>

<p>These functions facilitate access to hash maps.</p>

<ulp>

<li><code>(make-hashmap)</code>. Creates a new, empty hash map.</li>

<li><code>(hashmap? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a hash map, and <code>#f</code>
otherwise.</li>

<li><code>(hashmap-contains-key? <var>hashmap</var> <var>key</var>)</code>. Returns <code>#t</code> if the hashable
object <var>key</var> is in <var>hashmap</var>, and <code>#f</code> otherwise. If <var>key</var> is not hashable,
returns <code>#f</code>.</li>

<li><code>(hashmap-length <var>hashmap</var>)</code>. Returns the number of items in <var>hashmap</var>.</li>

<li><code>(hashmap-ref <var>hashmap</var> <var>key</var>)</code>. Returns the value associated with <var>key</var>
in <var>hashmap</var>. Returns <code>#f</code> if <var>key</var> is not found; throws an exception if <var>key</var>
is not hashable.</li>

<li><code>(hashmap-set! <var>hashmap</var> <var>key</var> <var>value</var>)</code>. Associates the hashable item
<var>key</var> with <var>value</var> in <var>hashmap</var>.</li>

<li><code>(hashmap-remove! <var>hashmap</var> <var>key</var>)</code>. Removes the association of <var>key</var>
in <var>hashmap</var>. This function throws an exception if <var>key</var> is not hashable or is not found.</li>

<li><code>(hashmap-keys <var>hashmap</var>)</code>. Returns a hash set containing the keys in <var>hashmap</var>.</li>

</ulp>

</section>

<section name="func_messagesandsignatures"><title>Message and Signature Functions</title>

<p>The following functions are useful with signatures.</p>

<ulp>

<li><code>(signature? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a signature,
and <code>#f</code> otherwise.</li>

<li><code>(signature-get-type <var>sig</var>)</code>. Returns the type symbol of the signature <var>sig</var>.</li>

<li><code>(signature-get-parameters <var>sig</var>)</code>. Returns a hashset containing the
signature <var>sig</var>&rsquo;s parameters.</li>

<li><code>(signature-has-parameter? <var>sig</var> <var>p</var>)</code>. Returns <code>#t</code> if the
signature <var>sig</var> has the parameter <var>p</var>, and <code>#f</code> otherwise.</li>

<li><code>(make-signature <var>type</var> <var>ps</var>)</code>. Creates and returns a new signature
whose type is the symbol <var>type</var> and whose parameters are taken from the hashset <var>ps</var>.
<var>ps</var> must contain only symbols.</li>

<li><code>(signature=? <var>sig1</var> <var>sig2</var>)</code>. Returns <code>#t</code> if the two given signatures
are equal, which is to say, if they have the same type and the same parameters. Returns
<code>#f</code> otherwise.</li>

</ulp>

<p>The following functions are useful with messages.</p>

<ulp>

<li><code>(message? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a message,
and <code>#f</code> otherwise.</li>

<li><code>(message-get-type <var>msg</var>)</code>. Returns the type symbol of the message <var>msg</var>.</li>

<li><code>(message-get-arguments <var>msg</var>)</code>. Returns a hashmap containing the message
<var>msg</var>&rsquo;s arguments.</li>

<li><code>(message-get-signature <var>msg</var>)</code>. Returns the signature of the message <var>msg</var>.</li>

<li><code>(message-has-argument? <var>msg</var> <var>a</var>)</code>. Returns <code>#t</code> if the
message <var>msg</var> has an argument <var>a</var>, and <code>#f</code> otherwise.</li>

<li><code>(message-ref <var>msg</var> <var>a</var>)</code>. Returns the value of the argument <var>a</var> in
<var>msg</var>.</li>

<li><code>(make-message <var>type</var> <var>args</var>)</code>. Creates and returns a new message whose type is the
symbol <var>type</var> and whose arguments are taken from the hashmap <var>args</var>.  The keys in <var>args</var>
must all be symbols.</li>

<li><code>(message-has-signature? <var>msg</var> <var>sig</var> <var>...</var>)</code>. Returns <code>#t</code> if
<var>msg</var> is a message and has any of the signatures given, and <code>#f</code> otherwise. If no <var>sig</var>
values are given, this function acts like <code>message?</code>.</li>

</ulp>

<p>Messages and signatures are immutable. Signatures are hashable.</p>

</section>

<section name="func_bytes"><title>Byte Array and Native Memory Functions</title>

<ulp>

<li><code>(make-bytes <var>n</var>)</code>. Makes an array of <var>n</var> bytes.</li>

<li><code>(bytes? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is an array of bytes,
and <code>#f</code> otherwise. This function returns <code>#f</code> for native memory.</li>

<li><code>(make-native-memory <var>n</var>)</code>. Uses the Windows API function <code>VirtualAlloc</code> to
allocate native memory, with a size of <var>n</var> bytes. Returns the Disposable ID of the memory. On 64-bit systems,
this can be used to allocate byte arrays larger than 4 GB.</li>

<li><code>(native-memory? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is the Disposable ID of a
native memory object, and <code>#f</code> otherwise.</li>

<li><code>(byte-length <var>bytes</var>)</code>. Determines the length of a byte array. (Also works with native
memory.)</li>

<li><code>(byte-ref <var>bytes</var> <var>i</var>)</code>. Retrieves the byte at offset <var>i</var> of the byte array
<var>bytes</var>. The byte is retrieved as an unsigned integer from <code>0</code> to <code>255</code>. (Also works
with native memory.)</li>

<li><code>(byte-set! <var>bytes</var> <var>i</var> <var>val</var>)</code>. Stores the value <var>val</var> into offset
<var>i</var> of the byte array <var>bytes</var>. <var>val</var> must be an integer, and only the least significant
byte of the integer is stored. (Also works with native memory.)</li>

<li><code>(byte-get-hbla <var>bytes</var>)</code>. Returns <code>#t</code> if <var>bytes</var> is set in high-byte
low-address mode, and <code>#f</code> otherwise. Each byte array has its own setting.</li>

<li><code>(byte-set-hbla! <var>bytes</var> <var>bool</var>)</code>. Sets <var>bytes</var> to high-byte low-address
mode if <var>bool</var> is true, and sets <var>bytes</var> to low-byte low-address mode if <var>bool</var> is
<code>#f</code>.</li>

<li><code>(byte-ref-double <var>bytes</var> <var>off</var>)</code>. Fetches an 8-byte IEEE float from
offset <var>off</var> in byte array <var>bytes</var>. Uses the byte-order setting of <var>bytes</var>.</li>

<li><code>(byte-set-double! <var>bytes</var> <var>off</var> <var>value</var>)</code>. Stores
<var>value</var> into byte array <var>bytes</var> at offset <var>off</var>, as an 8-byte IEEE float.
Uses the byte-order setting of <var>bytes</var>.</li>

<li><code>(byte-ref-float <var>bytes</var> <var>off</var>)</code>. Fetches a 4-byte IEEE float from
offset <var>off</var> in byte array <var>bytes</var>. Uses the byte-order setting of <var>bytes</var>.</li>

<li><code>(byte-set-float! <var>bytes</var> <var>off</var> <var>value</var>)</code>. Stores
<var>value</var> into byte array <var>bytes</var> at offset <var>off</var>, as a 4-byte IEEE float.
Uses the byte-order setting of <var>bytes</var>.</li>

<li><code>(byte-size-of-integer <var>int</var> <var>signed?</var>)</code>. Returns the number of bytes necessary to
represent the integer <var>int</var>. If <var>signed?</var> is <code>#t</code>, returns enough bytes to accommodate
the sign bit; if <var>signed?</var> is <code>#f</code>, assumes the sign bit is stored elsewhere.</li>

<li><code>(integer-&gt;bytes <var>int</var> <var>hbla</var>)</code>. Converts the integer <var>int</var> to a
byte array. The byte array always includes the sign bit. <var>hbla</var> must be <code>#t</code> for high-byte
low-address, or <code>#f</code> for low-byte low-address.</li>

</ulp>

</section>

<section name="byterange"><title>Byte Array Range Functions</title>

<p>These types make it possible to specify a range of a byte array or a region of native memory. Byte ranges are
immutable even though the bytes covered by the ranges are not.</p>

<ulp>

<li><code>(byterange <var>array</var> <var>off</var> <var>len</var>)</code>. Returns a new byte range over the byte
array or native memory object <var>array</var>. <var>off</var> (the offset) and <var>len</var> (the length) are
optional. If neither are specified, the range is returned that covers the entire array. If only <var>off</var> is
specified, a range is returned that covers the entire array except for the first <var>off</var>
bytes. If <var>off</var> and <var>len</var> are both specified, a range is returned that covers the designated
area.</li>

<li><code>(byterange? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a byte range,
and <code>#f</code> otherwise.</li>

<li><code>(byterange-array-backed? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a byte range
that covers an ordinary byte array, and <code>#f</code> otherwise. In particular, returns <code>#f</code>
if <var>obj</var> is a byte range covering native memory.</li>

<li><code>(byterange-native? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a byte range that
covers native memory, and <code>#f</code> otherwise. In particular, returns <code>#f</code> if <var>obj</var> is a
byte range covering a byte array.</li>

<li><code>(byterange-bytes <var>range</var>)</code>. Returns the entire byte array which is referred to by the
range <var>range</var>. (This does not work if the byte range covers native memory.)</li>

<li><code>(byterange-offset <var>range</var>)</code>. Returns the offset in the given range. (This does not work if
the byte range covers native memory.)</li>

<li><code>(byterange-length <var>range</var>)</code>. Returns the length in the given range. (This works for byte
ranges covering either byte arrays or native memory.)</li>

<li><code>(byterange-valid? <var>range</var>)</code>. Returns <code>#t</code> if <var>range</var> covers a valid part
of its byte array, and <code>#f</code> otherwise. (This does not work for byte ranges covering native memory.)</li>

<li><code>(byterange-&gt;bytes <var>range</var>)</code>. Returns a new byte array containing a copy of only the bytes
that were covered by <var>range</var>. (This does not work for byte ranges covering native memory.)</li>

<li><code>(byterange-left <var>range</var> <var>n</var>)</code>. Returns a new range containing only the leftmost
<var>n</var> bytes of <var>range</var>. If <var>range</var> has fewer than <var>n</var> bytes, a copy of it is
returned.</li>

<li><code>(byterange-right <var>range</var> <var>n</var>)</code>. Returns a new range containing only the rightmost
<var>n</var> bytes of <var>range</var>. If <var>range</var> has fewer than <var>n</var> bytes, a copy of it is
returned.</li>

<li><code>(byterange-trim-left <var>range</var> <var>n</var>)</code>. Returns a new range containing all but the
leftmost <var>n</var> bytes of <var>range</var>. If <var>range</var> has fewer than <var>n</var> bytes, returns a
range with a length of zero.</li>

<li><code>(byterange-trim-right <var>range</var> <var>n</var>)</code>. Returns a new range containing all but the
rightmost <var>n</var> bytes of <var>range</var>. If <var>range</var> has fewer than <var>n</var> bytes, returns a
range with a length of zero.</li>

</ulp>

<p>These functions use byte ranges to manipulate byte arrays.</p>

<ulp>

<li><code>(byte-copy! <var>srcrange</var> <var>destrange</var>)</code>. Copies bytes from the source range to the
destination range. The number of bytes copied is equal to the lesser of the lengths of the two ranges. If the ranges
overlap, the effectiveness of this operation is not guaranteed. (The ranges can cover byte arrays or native
memory.)</li>

<li><code>(byte-fill! <var>destrange</var> <var>b</var>)</code>. Replaces <var>len</var> bytes in the byte
array <var>dest</var>, starting at offset <var>off</var>, with the byte <var>b</var>. Only the least significant byte
of the integer <var>b</var> is used. (The ranges can cover byte arrays or native memory.)</li>

<li><code>(byte-ref-int <var>byterange</var>)</code>. Fetches a signed integer from the given byte range. The signed
integer is assumed to occupy the entire range. Uses the byte order setting of the byte array underlying the
range.</li>

<li><code>(byte-ref-uint <var>byterange</var>)</code>. Fetches an unsigned integer from the given byte range.  The
unsigned integer is assumed to occupy the entire range. Uses the byte order setting of the byte array underlying the
range.</li>

<li><code>(byte-set-int! <var>byterange</var> <var>value</var>)</code>. Stores an integer
<var>value</var> into the given byte range. The value of the integer wraps around in the event of overflow, and thus
this function works the same way for signed and unsigned integers. Uses the byte-order setting of the underlying byte
array.</li>

<li><code>(byte-set-int-s! <var>byterange</var> <var>value</var>).</code> Stores an integer
<var>value</var> into the given byte range, using signed saturation. Uses the byte-order setting of the underlying
byte array.</li>

<li><code>(byte-set-uint-s! <var>byterange</var> <var>value</var>).</code> Stores an integer
<var>value</var> into the given byte range, using unsigned saturation. Uses the byte-order setting of the underlying
byte array.</li>

<li><code>(byte-ref-string <var>byterange</var>)</code>. Fetches a string from the given byte range. A zero byte is
considered a null terminator, but in the absence of a null terminator a string of length <var>len</var> will be
returned. Bytes with values from <code>1</code> to <code>255</code> are converted directly to those characters.</li>

<li><code>(byte-set-string! <var>byterange</var> <var>str</var>)</code>. Stores a string into the given byte range. If
the string is longer then <var>len</var> characters, only the first <var>len</var> characters are stored. If the
string contains characters with codes greater than <code>255</code>, only the least significant byte of the character
is stored. If the string is too short to fill the field, the field is filled with null terminators after the
string.</li>

<li><code>(dump <var>byterange</var>)</code>. Hex-dumps the given byte range to the screen. (This function works for
byte ranges covering arrays or native memory.)</li>

</ulp>

</section>

<section name="func_codec"><title>Codec Generation</title>

<p>Sunlit World Scheme has a codec generator which takes a description of a data structure and returns functions to
convert that data structure to an array of bytes and back. These functions, taken together, can be described as a
codec (i.e., coder / decoder). The codec generator can be used to format data for transmission over a network, or for
storage.</p>

<p>The codec generator deals properly with recursive data structures and recursive types.</p>

<ulp>

<li><code>(make-codec <var>desc</var> <var>proc</var>)</code>. <var>desc</var> must be a codec description in a
special language described below. <var>proc</var> must be a procedure, which will be called
as <code>(<var>proc</var> <var>read</var> <var>can-write?</var> <var>write</var>)</code>. When you call
<code>(<var>read</var> <var>bytearray</var>)</code>, the byte array is converted into Scheme data of a type described
by the codec. When you call <code>(<var>can-write?</var> <var>obj</var>)</code>, you get <code>#t</code>
if <var>obj</var> is of a type described by the codec and <code>#f</code> otherwise. When you
call <code>(<var>write</var> <var>obj</var>)</code>, you get a byte array containing the coded form of <var>obj</var>,
or an exception if <var>obj</var> does not conform to the requirements of the codec.</li>

</ulp>

<p>The codec description can consist of any of the following primitive types:</p>

<ul>
<li><code>byte</code>. An integral type only matches an integer, and only if the integer fits in its range.</li>
<li><code>short</code>.</li>
<li><code>int</code>.</li>
<li><code>long</code>.</li>
<li><code>sbyte</code>.</li>
<li><code>ushort</code>.</li>
<li><code>uint</code>.</li>
<li><code>ulong</code>. </li>
<li><code>bigint</code>. This type matches any Scheme integer, and has no range limitations.</li>

<li><code>rational</code>. This type matches any Scheme integer or rational number, and has no range limitations.</li>

<li><code>float</code>. A floating-point type can match any Scheme number. Conversion may lose precision.</li>

<li><code>double</code>. A double-precision floating-point type can match any Scheme number. Conversion may lose
precision.</li>

<li><code>number</code>. Any Scheme number (integer, rational, or floating-point). Value and type will be
preserved.</li>

<li><code>string</code>. A Scheme string. Strings are written by reference. UTF-8 is used, so unpaired surrogates
won&rsquo;t encode.</li>

<li><code>symbol</code>. Matches a Scheme symbol. Symbols are written by reference. Uninterned symbols come back as
different uninterned symbols, but if two symbols are the same as each other going in, they will be the same as each
other coming out. Interned symbols are identified with UTF-8, so unpaired surrogates won&rsquo;t encode.</li>

<li><code>bool</code>. A boolean.</li>
<li><code>char</code>. A character.</li>
<li><code>guid</code>. A globally unique identifier.</li>

<li><code>byte-array</code>. A byte array. The encoder will accept a byte range, but the decoder always produces a freshly
allocated byte array for each byte range. Byte arrays are written by reference.</li>

<li><code>empty-list</code>. The empty list. This is encoded as zero bytes.</li>

<li><code>eof</code>. The EOF object. This is encoded as zero bytes.</li>

<li><code>(the-symbol <var>sym</var>)</code>. Matches the specific symbol <var>sym</var>. This is encoded as zero bytes.</li>

<li><code>#t</code>. Matches the boolean <code>#t</code>. This is encoded as zero bytes.</li>
<li><code>#f</code>. Matches the boolean <code>#f</code>. This is encoded as zero bytes.</li>

</ul>

<p>The following expressions and combinators are also available.</p>

<ulp>

<li>A message (see <xref dest="messagesandsignatures"/>) whose arguments are codec descriptions will create a codec
that matches messages with the same signature whose arguments match the given codec descriptions. For example,
<code>#msg(test . x string y byte)</code> will match <code>#msg(test . x "string" y 100)</code>. A message with no
arguments will produce a zero-byte codec.</li>

<li><code>(letrec (<var>clause</var> <var>...</var>) <var>body</var>)</code>. Each <var>clause</var> must be of the
form <code>(<var>name</var> <var>desc</var>)</code>, where <var>name</var> is a symbol and <var>desc</var> is a codec
description. This allocates a variable for each <var>name</var>, then evaluates each <var>desc</var> in an environment
where all the <var>name</var> variables are already defined, then finally evaluates <var>body</var> in the same
environment.  This allows recursive type definitions.</li>

<li><code>(ref <var>name</var>)</code>. A reference to the variable <var>name</var>.</li>

<li><code>(byte-case <var>clause</var> <var>...</var>)</code>. Each <var>clause</var> must be of the form
<code>(<var>byte</var> <var>desc</var>)</code>. When writing, this codec matches the described type against the
clauses in order.  When it finds the first match, it writes the byte and then lets the described type&rsquo;s codec
write the data. When reading, this codec reads the byte first and then uses the codec described in the clause to read
the data.</li>

<li><code>(list-of <var>desc</var>)</code>. Represents a list of the item described by <var>desc</var>. The list may
contain zero or more elements, but may not be dotted.</li>

<li><code>(vector-of <var>desc</var>)</code>. Represents a vector of the item described by <var>desc</var>.</li>

<li><code>(cons <var>desc1</var> <var>desc2</var>)</code>. Represents a cons cell whose <code>car</code> is described
by <var>desc1</var> and whose <code>cdr</code> is described by <var>desc2</var>.</li>

</ulp>

</section>

<section name="func_console"><title>Console Functions</title>

<ulp>

<li><code>(page!)</code>. Clears the screen.</li>

<li><code>(set-consize! <var>x</var> <var>y</var>)</code>. Changes the size of the console to <var>x</var>
horizontally by <var>y</var> vertically.</li>

<li><code>(display-string! <var>str</var>)</code>. Writes the characters of the string <var>str</var> to the
console.</li>

<li><code>(getkey)</code>. Stops and waits for a keypress, then returns a vector of the form <code>#(<var>char</var>
<var>key</var> <var>modifiers</var>)</code>. <var>char</var> is a character or <code>#\nul</code> if the keystroke
didn&rsquo;t correspond to a character. <var>key</var> is an integer key code, and <var>modifiers</var> is an integer
whose bits indicate whether ALT, CTRL, or SHIFT were pressed.</li>

<li><code>(set-color! <var>fg</var> <var>bg</var>)</code>. Sets the current color (which affects future output until
the color is changed again) to the foreground <var>fg</var> and the background <var>bg</var>. <var>fg</var> and
<var>bg</var> must be integers in the range <code>0</code> to <code>15</code>.</li>

<li><code>(goto-xy! <var>x</var> <var>y</var>)</code>. Moves the console cursor to the position <var>x</var>
horizontally and <var>y</var> vertically. Positions are zero-based.</li>

<li><code>(readline)</code>. Stops and waits for the user to enter a string, and returns the string.</li>

<li><code>(begin-readline)</code>. Starts a readline as an asynchronous operation.</li>

</ulp>

</section>

<section name="func_proc"><title>Procedure, Continuation, and Exception Functions</title>

<ulp>

<li><code>(procedure? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a procedure, and
<code>#f</code> if it is not.</li>

<li><code>(arity <var>proc</var>)</code>. Returns the minimum number of arguments that the procedure <var>proc</var>
will accept.</li>

<li><code>(more-arity? <var>proc</var>)</code>. Returns <code>#t</code> if a procedure accepts more than the minimum
number of arguments, and <code>#f</code> otherwise.</li>

<li><code>(call-with-current-continuation <var>proc</var>)</code>, where <var>proc</var> can be called as
<code>(<var>proc</var> <var>cc</var>)</code>. Captures the current continuation and passes it to <var>proc</var> as
the argument <var>cc</var>, which is a procedure. Calling this procedure with an argument <var>x</var> has the
same effect as if the call to <code>call-with-current-continuation</code> had returned <var>x</var>.</li>

<li><code>(call-with-current-exception-handler <var>proc</var>)</code>, where <var>proc</var> can be called as
<code>(<var>proc</var> <var>eh</var>)</code>. Captures the current exception handler and passes it to <var>proc</var>
as the argument <var>eh</var>, which is a procedure. Calling this procedure with an argument <var>exc</var> has
the same effect as if the call to <code>call-with-current-exception-handler</code> had thrown <var>exc</var>.</li>

<li><code>(throw <var>obj</var>)</code>. Throws <var>obj</var> as an exception. Any object can be thrown. This
function could be defined as <code>(define throw (lambda (exc) (call-with-current-exception-handler (lambda (th)
(th exc)))))</code>.</li>

<li><code>(exception? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is an exception descending
from <code>System.Exception</code> in the dot-Net framework. Otherwise returns <code>#f</code>. In Scheme, it is
possible to throw any object, not just descendants of <code>System.Exception</code>.</li>

<li><code>(exception-&gt;string <var>exc</var>)</code>. Gets the message of the exception <var>exc</var> as a
string.</li>

</ulp>

<p>The following functions are for message procedures created by <code>mlambda</code>.</p>

<ulp>

<li><code>(mprocedure? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a message
procedure, and <code>#f</code> otherwise.</li>

<li><code>(msignature <var>mproc</var>)</code>. Returns the signature of the given message procedure.</li>

<li><code>(minvoke <var>mproc</var> <var>msg</var>)</code>. Invokes the message procedure <var>mproc</var>
with the message <var>msg</var> as an argument. If the signature of <var>msg</var> matches that of <var>mproc</var>,
returns a pair <code>(#t . <var>val</var>)</code>, where <var>val</var> is the return value of <var>mproc</var>.
If the signature does not match, returns the pair <code>(#f . #f)</code>.</li>

</ulp>

</section>

<section name="disp_list"><title>Disposable Object Functions</title>

<p>These functions provide support for disposable objects.</p>

<p>Disposable objects are kept in a global list. That means there&rsquo;s no way to &ldquo;lose&rdquo; a disposable
object. Anything that leaks out of your code can be disposed manually from the interpreter prompt.</p>

<ulp>

<li><code>(disposable-id <var>int</var>)</code>. Converts the integer <var>int</var> to a Disposable ID.</li>

<li><code>(disposable-id? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a Disposable ID,
and <code>#f</code> otherwise.</li>
  
<li><code>(dispose! <var>id</var>)</code>. <var>id</var> must be a Disposable ID. Disposes of the object with that ID.</li>

<li><code>(list-disposables)</code>. This function is primarily intended for use from the interpreter. It returns a
list of all known disposable objects. Each item in the list is of the form <code>#m((id . <var>id</var>) (desc
. <var>desc</var>))</code>, where <var>id</var> is the Disposable ID of the object and <var>desc</var> is a string
which the implementation assigns to help users identify the disposable object.</li>
  
</ulp>
  
</section>

<section name="threads"><title>Thread Functions</title>

<p>Sunlit World Scheme allows you to create auxiliary threads. These threads run in the dot-Net thread pool.</p>

<p>Large parts of Sunlit World Scheme are not thread safe; therefore, it is advisable not to allow threads to access
each other&rsquo;s data. It is possible to set up synchronization mechanisms to allow sharing of data, though.</p>

<ulp>

<li><code>(begin-thread <var>proc</var>)</code>. <var>proc</var> should be a procedure that does not take any
arguments. <code>begin-thread</code> begins a thread, and returns an AsyncID that can be used to wait on the result of
the thread, which is the return value of <var>proc</var>, or any unhandled exception.</li>

</ulp>

<p>AsyncIDs are described in the next section.</p>

</section>

<section name="async_list"><title>Asynchronous Operation Functions</title>

<p>The interpreter keeps all asynchronous operations in a global list. This means there&rsquo;s no way to lose track
of any asynchronous operation. In general, asynchronous operations are not abortable; you have to wait for them to
complete. However, there are specific exceptions; for example, a socket read can be forced to complete immediately by
closing the socket while the read is in progress.</p>

<p>An asynchronous operation may already be completed. The interpreter will continue to track it until its result is
retrieved. Retrieval of a result is done by waiting on the operation. If the operation has already completed, the wait
takes zero time.</p>

<ulp>

<li><code>(async-id <var>int</var>)</code>. Converts the integer <var>int</var> to an Async ID.</li>

<li><code>(async-id? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is an Async ID,
and <code>#f</code> otherwise.</li>

<li><code>(is-completed? <var>asyncid</var>)</code>. Returns <code>#t</code> if the asynchronous
operation given by <var>asyncid</var> has already completed, and <code>#f</code> otherwise.</li>

<li><code>(list-asyncs)</code>. This function is primarily intended for use from the interpreter. It returns
a list of all the asynchronous operations in progress. Each item in the list is a hash map of the form
<code>#m((id . <var>id</var>) (desc . <var>desc</var>) (wait-in-progress . <var>waitflag</var>))</code>,
where <var>id</var> is the Async ID of the operation, <var>desc</var> is a string assigned by the implementation which
may help users identify the operation, and <var>waitflag</var> indicates whether another thread was waiting on the
operation at the time <code>list-asyncs</code> was called.</li>

<li><code>(wait-any <var>asyncid</var> <var>...</var>)</code>. Waits, if necessary, then retrieves the result of the
first asynchronous operation (from among the arguments) to complete. If one operation is already completed at the time
this function is invoked, it is returned. If multiple operations have already completed, any one of them may be
returned. If multiple operations complete at the same time, any one of them may be returned.  If you pass only one
asynchronous operation, it will be the first to complete. It is an error to pass any asynchronous operation which is
already being waited on by another thread.</li>
  
</ulp>

<p>The return value of <code>wait-any</code> is a hash map of the form
<code>#m((result . <var>result</var>) (id . <var>id</var>) (exception? . <var>exc</var>))</code>, where
<var>result</var> is the result
of the operation (or the exception that was thrown), <var>id</var> is the original Async ID of the operation,
and <var>exc</var> is <code>#t</code> if the result was an exception and <code>#f</code> if the result was
an ordinary return value.</p>

<p>It is not possible for two threads to wait on the same asynchronous operation at the same time. The result of the
asynchronous operation can only be delivered once, to a single waiting thread. However, the asynchronous operation
does not belong to any particular thread. If a thread waits on two operations, and one of the operations completes,
the other operation is then available to be waited upon by any thread. Thus, it is possible for a single
asynchronous operation to be waited upon by any number of threads, as long as only one thread waits on it at a
time.</p>

</section>

<section name="threadpool"><title>Thread Pool Functions</title>

<p>Sunlit World Scheme draws its threads from the dot-Net thread pool. Thus if the dot-Net thread pool is exhausted,
Sunlit World Scheme will not be able to create a new thread.</p>

<p>The following functions are provided to read and write the dot-Net thread pool settings.</p>

<ulp>

<li><code>(threadpool-get-min-workers)</code>. Returns the minimum number of permitted worker threads.</li>

<li><code>(threadpool-get-min-completion-port-threads)</code>. Returns the minimum number of permitted completion port
threads.</li>

<li><code>(threadpool-get-max-workers)</code>. Returns the maximum number of permitted worker threads.</li>

<li><code>(threadpool-get-max-completion-port-threads)</code>. Returns the maximum number of permitted completion port
threads.</li>

<li><code>(threadpool-get-available-workers)</code>. Returns the number of worker threads that exist and are idle, or
can be created.</li>

<li><code>(threadpool-get-available-completion-port-threads)</code>. Returns the number of completion port threads
that exist and are idle, or can be created.</li>

<li><code>(threadpool-set-min-workers! <var>i</var>)</code>. Sets the minimum permitted number of worker threads
to <var>i</var>.</li>

<li><code>(threadpool-set-min-completion-port-threads! <var>i</var>)</code>. Sets the minimum permitted number of
completion port threads to <var>i</var>.</li>

<li><code>(threadpool-set-max-workers! <var>i</var>)</code>. Sets the maximum permitted number of worker threads
to <var>i</var>.</li>

<li><code>(threadpool-set-max-completion-port-threads! <var>i</var>)</code>. Sets the maximum permitted number of
completion port threads to <var>i</var>.</li>

</ulp>

</section>

<section name="func_objects"><title>Object System Functions</title>

<p>The Object System in Sunlit World Scheme is an implementation of the Actor Model. It is based on message
passing. The message-passing operation, given by the function <code>post!</code>, is unidirectional, asynchronous,
reliable, and ordered (in the sense that if a single thread posts two or more messages, they will arrive in the order
posted; no guarantees are made regarding messages posted from different threads). An object is allowed to process only
one message at a time, but multiple objects may be processing messages on multiple threads at the same time. The
Object System runs in parallel with the interpreter, and it is possible to modify objects while they are running.</p>

<p>The following functions are used with the object system.</p>

<ulp>

<li><code>(object-id <var>i</var>)</code>. Creates an Object ID from the given integer.</li>

<li><code>(object-id? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is an Object ID,
and <code>#f</code> otherwise.</li>

<li><code>(make-object)</code>. Creates a new blank user-definable object in the object system, and returns its Object
ID.</li>

<li><code>(set-handler! <var>objectid</var> <var>mproc</var>)</code>. Adds or replaces a message handler in the
user-definable object identified by <var>objectid</var>. This does not work if <var>objectid</var> does not refer to a
user-definable object. <var>mproc</var> must be a message procedure. Returns <code>#t</code> if the request is
successfully queued, and <code>#f</code> otherwise.</li>
 
<li><code>(unset-handler! <var>objectid</var> <var>sig</var>)</code>. Removes the message handler with the
signature <var>sig</var> in the object identified by <var>objectid</var>. This does not work if <var>objectid</var>
does not refer to a user-definable object. Returns <code>#t</code> if the removal request is succesfully queued,
and <code>#f</code> otherwise.</li>

<li><code>(list-handlers <var>objectid</var>)</code>. Returns a hashset of signatures indicating which messages the
object given by <var>objectid</var> has handlers for. (This function posts a message to the object and waits for the
object to respond. If the object is busy, this function will block.)</li>

<li><code>(begin-list-handlers <var>objectid</var>)</code>. Starts an asynchronous operation which will return
a hashset of signatures indicating which messages are handled by the object given by <var>objectid</var>.</li>

<li><code>(set-catch-all! <var>objectid</var> <var>proc</var>)</code>. Sets the catch-all handler on the object
identified by <var>objectid</var> to <var>proc</var>. This does not work if <var>objectid</var> does not refer to a
user-definable object. The procedure <var>proc</var> must accept a single argument, which will be the message that was
not handled by any of the handlers.</li>

<li><code>(unset-catch-all! <var>objectid</var>)</code>. Unsets the catch-all handler on the object identified by
<var>objectid</var>. This does not work if <var>objectid</var> does not refer to a user-definable object. If a message
is not handled by any handlers, and no catch-all is set, the message will be ignored.</li>

<li><code>(add-local! <var>objectid</var> <var>name</var> <var>initval</var>)</code>. Posts a message to the
object <var>objectid</var> that will cause it to create a new local variable slot with the name <var>name</var> and
the initial value <var>initval</var>. <var>name</var> must evaluate to a symbol.</li>

<li><code>(remove-local! <var>objectid</var> <var>name</var>)</code>. Posts a message to the object
<var>objectid</var> that will cause it to remove a local variable slot with the name <var>name</var>. <var>name</var>
must evaluate to a symbol.</li>

<li><code>(list-locals <var>objectid</var>)</code>. Returns a hashset of symbols naming the local variables that the
object <var>objectid</var> has. (This function posts a message to the object and waits for the object to respond. If
the object is busy, this function will block.)</li>

<li><code>(begin-list-locals <var>objectid</var>)</code>. Returns an asynchronous operation which will return a
hashset of symbols naming the local variables that the object <var>objectid</var> has.</li>

<li><code>(post! <var>objectid</var> <var>msg</var>)</code>. Posts the message <var>msg</var> to the object
<var>objectid</var>. Returns <code>#t</code> if the message is succesfully queued, and <code>#f</code> otherwise.</li>

<li><code>(post-later! <var>delay</var> <var>objectid</var> <var>msg</var> <var>proc</var>)</code>. Posts the message
<var>msg</var> to the object <var>objectid</var> after a delay of <var>delay</var> milliseconds. <var>delay</var> must
be an integer less than <code>4294967296</code> but not less than <code>0</code>. The <var>proc</var> argument is
optional; if specified, it must be a procedure of one parameter. If the message becomes undeliverable, <var>proc</var>
is called in a separate threaed with <var>msg</var> as its argument. If the message is successfully posted to the
object, <var>proc</var> is never called. (The purpose of <var>proc</var> is to dispose of any disposable data
in <var>msg</var>.) <code>post-later!</code> returns the unspecified value.</li>

<li><code>(self)</code>. When executed inside a message handler, returns the Object ID of the current object.  Returns
<code>#f</code> when executed outside of a message handler.</li>

<li><code>(list-objects)</code>. Returns a list of the objects that currently exist.</li>

<li><code>(remove-object! <var>objectid</var>)</code>. Removes the object given by <var>objectid</var>. The object is
not given any notice that it is being removed. Ideally, objects should only remove themselves.</li>

<li><code>(with-get-from-temporary <var>proc</var>)</code>. Constructs a temporary object, begins an asynchronous
&ldquo;get message&rdquo; operation on it, and then calls <code>(<var>proc</var> <var>tempobj</var>
<var>getop</var>)</code>. <var>proc</var> must be a procedure that accepts two arguments. <var>tempobj</var> will be
the Object ID of the temporary object. <var>getop</var> will be the Async ID of the &ldquo;get message&rdquo;
operation. This function can be used to post a message to an object and get a response. Messages that are intended to
evoke responses typically have a <code>k</code> argument containing the Object ID to which the response should be
posted. The <var>proc</var> typically posts such a message to another object, passing <var>tempobj</var> for
<code>k</code>. The temporary object self-destructs after receiving one message.</li>

</ulp>

<p>See also <xref dest="messagesandsignatures"/>, <xref dest="messagelambdas"/>, <xref dest="local"/>, and
<xref dest="func_proc"/>.</p>

</section>

<section name="graphics"><title>Graphics Functions</title>

<p>These functions provide graphics functionality.</p>

<p>Bitmaps, Graphics objects, Pens, Brushes, and Fonts are all Disposable. Therefore, when a function is called that
creates one of the objects, the Disposable ID is returned. When a function takes one of these objects as an argument,
the Disposable ID of the object should be given.</p>

<p>Remember to eventually call <code>dispose!</code> on objects that are no longer needed.</p>
  
<ulp>

<li><code>(make-bitmap <var>width</var> <var>height</var>)</code>. Creates a bitmap with a width of <var>width</var>
and a height of <var>height</var>. The Disposable ID of the bitmap is returned.</li>

<li><code>(bitmap-x-size <var>bitmap</var>)</code>. Returns the width of the bitmap.</li>

<li><code>(bitmap-y-size <var>bitmap</var>)</code>. Returns the height of the bitmap.</li>

<li><code>(pixel-ref <var>bitmap</var> <var>x</var> <var>y</var>)</code>. Returns the color at the given pixel in the
given bitmap.</li>

<li><code>(pixel-set! <var>bitmap</var> <var>x</var> <var>y</var> <var>color</var>)</code>. Sets the given pixel in
the given bitmap to the given color.</li>

<li><code>(make-graphics-for-bitmap <var>bitmap</var>)</code>. Creates a graphics object that can be used to draw
on <var>bitmap</var>.</li>

<li><code>(rgb <var>r</var> <var>g</var> <var>b</var>)</code>. Creates a color from its RGB values. The integers
<var>r</var>, <var>g</var>, and <var>b</var> must be from <code>0</code> to <code>255</code>.</li>

<li><code>(make-pen <var>color</var>)</code>. Makes and returns a pen with the given color, of width one.</li>

<li><code>(make-pen-with-width <var>color</var> <var>width</var>)</code>. Makes and returns a pen of the given color
with the given width.</li>

<li><code>(make-solid-brush <var>color</var>)</code>. Makes and returns a solid-color brush of the given color.</li>

<li><code>(pointf <var>x</var> <var>y</var>)</code>. Makes and returns a pointf structure with the given floating-point
<var>x</var> and <var>y</var> positions.</li>

<li><code>(make-gradient-brush <var>point1</var> <var>color1</var> <var>point2</var>
<var>color2</var>)</code>. Makes a linear gradient brush with the given points and colors.</li>

<li><code>(graphics-draw-bitmap! <var>graphics</var> <var>bitmap</var> <var>pointf</var>)</code>. Draws <var>bitmap</var>
on <var>graphics</var>, with its upper-left corner at <var>pointf</var>.</li>

<li><code>(graphics-line! <var>graphics</var> <var>pen</var> <var>p1</var> <var>p2</var>)</code>. Draws a line with
the pen <var>pen</var> from the pointf <var>p1</var> to the pointf <var>p2</var>.</li>

<li><code>(graphics-fill-rect! <var>graphics</var> <var>brush</var> <var>p1</var> <var>p2</var>)</code>. Interprets
the pointf <var>p1</var> and the pointf <var>p2</var> as opposing corners of a rectangle, and draws a filled rectangle
with the brush <var>brush</var>.</li>

<li><code>(graphics-clear! <var>graphics</var> <var>color</var>)</code>. Clears the drawing surface with the color
<var>color</var>.</li>

<li><code>(display-bitmap! <var>bitmap</var>)</code>. Creates a form, displays the bitmap, and does not return until
the user closes the form.</li>

<li><code>(save-bitmap-png! <var>bitmap</var> <var>filename</var>)</code>. Saves the bitmap in PNG format to the given
filename.</li>

</ulp>

</section>

<section name="grlang"><title>Graphics Language Functions</title>

<p>A new graphics language has been introduced in order to make it easier to perform complex drawing operations. This
is used by two Scheme functions and by the window object.</p>

<p>Here are the Scheme functions.</p>

<ulp>

<li><code>(graphics-draw! <var>graphics</var> <var>drawing</var>)</code>. Draws <var>drawing</var> using the graphics
object <var>graphics</var>. <var>drawing</var> is a Scheme list written in the graphics language.</li>

<li><code>(window-draw! <var>window</var> <var>drawing</var>)</code>. <var>window</var> must be the Disposable ID of a
window. Draws <var>drawing</var> on the window&rsquo;s client area.</li>

</ulp>

<p>The grammar for the <var>drawing</var> list is as follows.</p>

<ulp>

<li><var>drawing</var> =&gt; <code>(clear <var>color</var>)</code>. Clears the drawing to <var>color</var>.</li>

<li><var>drawing</var> =&gt; <code>(displace (<var>dx</var> <var>dy</var>) <var>drawing</var> <var>...</var>)</code>.
Draws the <var>drawing</var> sub-drawings displaced <var>dx</var> pixels to the right and <var>dy</var> pixels
downward. <var>dx</var> and <var>dy</var> must be real numbers.</li>

<li><var>drawing</var> =&gt; <code>(clip-inside <var>region</var> <var>drawing</var> <var>...</var>)</code>.  Draws
only the portion of the <var>drawing</var> sub-drawings that appears inside <var>region</var>.</li>

<li><var>drawing</var> =&gt; <code>(clip-outside <var>region</var> <var>drawing</var> <var>...</var>)</code>.  Draws
only the portion of the <var>drawing</var> sub-drawings that appears outside <var>region</var>.</li>

<li><var>drawing</var> =&gt; <code>(line <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var>)</code>.  Draws a
line from (<var>x1</var>, <var>y1</var>) to (<var>x2</var>, <var>y2</var>) using the current pen.  The coordinates
must be real numbers.</li>

<li><var>drawing</var> =&gt; <code>(fill-rect <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var>)</code>.  Draws
a filled rectangle using the current brush, with (<var>x1</var>, <var>y1</var>) and (<var>x2</var>, <var>y2</var>) as
opposing corners.</li>

<li><var>drawing</var> =&gt; <code>(fill-polygon <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var> <var>x3</var>
<var>y3</var> <var>...</var>)</code>. Draws a filled polygon using the current brush, with the given corners. At least
three corners must be specified.</li>

<li><var>drawing</var> =&gt; <code>(text <var>x</var> <var>y</var> <var>text</var>)</code>. Draws text using the
current font with (<var>x</var>, <var>y</var>) as the upper-left corner.</li>

<li><var>drawing</var> =&gt; <code>(with-pen <var>color</var> <var>drawing</var> <var>...</var>)</code>. Draws
the <var>drawing</var> sub-drawings with a current pen of width 1 and color <var>color</var>.</li>

<li><var>drawing</var> =&gt; <code>(with-solid-brush <var>color</var> <var>drawing</var> <var>...</var>)</code>.
Draws the <var>drawing</var> sub-drawings with a current brush of color <var>color</var>.</li>

<li><var>drawing</var> =&gt; <code>(with-font <var>font</var> <var>drawing</var> <var>...</var>)</code>. Draws the
<var>drawing</var> sub-drawings with a current font described by <var>font</var>.</li>

<li><var>drawing</var> =&gt; <code>(begin <var>drawing</var> <var>...</var>)</code>. Draws the <var>drawing</var>
sub-drawings, in order from left to right. This is used to group many drawings into one.</li>

<li><var>color</var> =&gt; <code>(color <var>name</var>)</code>. Gives the color with the name <var>name</var>, which
must be a symbol. The color name must match one of those defined in <code>System.Drawing.Color</code>. Matching is
case-sensitive.</li>

<li><var>color</var> =&gt; <code>(rgb <var>r</var> <var>g</var> <var>b</var>)</code>. Gives the color with the given
RGB components. <var>r</var>, <var>g</var>, and <var>b</var> must all be integers from <code>0</code> to
<code>255</code> inclusive.</li>

<li><var>region</var> =&gt; <code>(rect <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var>)</code>. Gives the
rectangular region with (<var>x1</var>, <var>y1</var>) and (<var>x2</var>, <var>y2</var>) as opposing corners.</li>

<li><var>region</var> =&gt; <code>(polygon <var>x1</var> <var>y1</var> <var>x2</var> <var>y2</var> <var>x3</var>
<var>y3</var> <var>...</var>)</code>. Gives the polygonal region with the given corners. At least three corners must
be specified.</li>

<li><var>region</var> =&gt; <code>(union <var>region</var> <var>...</var>)</code>. Gives the union of the given
regions. If no regions are specified, gives the empty region. If one region is specified, returns it.</li>

<li><var>region</var> =&gt; <code>(intersection <var>region</var> <var>...</var>)</code>. Gives the intersection of
the given regions. If no regions are specified, gives the infinite region. If one region is specified, returns
it.</li>

<li><var>region</var> =&gt; <code>(difference <var>region1</var> <var>region2</var> <var>...</var>)</code>. Gives the
region <var>region1</var> minus the union of the regions <var>region2</var> and so forth. If only <var>region1</var>
is specified, it is returned.</li>

<li><var>region</var> =&gt; <code>(symmetric-difference <var>region</var> <var>...</var>)</code>. Gives the symmetric
difference of the given regions (the region covered by an odd number of the input regions). If no regions are
specified, gives the empty region. If one region is specified, returns it.</li>

<li><var>font</var> =&gt; <code>(font <var>name</var> <var>fontsize</var>)</code>. Gives the font with the given name
and size.</li>

<li><var>font</var> =&gt; <code>(bold <var>font</var>)</code>. Gives the bold version of the given font.</li>

<li><var>font</var> =&gt; <code>(italic <var>font</var>)</code>. Gives the italic version of the given font.</li>

<li><var>font</var> =&gt; <code>(underline <var>font</var>)</code>. Gives the underline version of the given font.</li>

<li><var>font</var> =&gt; <code>(strikeout <var>font</var>)</code>. Gives the strikeout version of the given font.</li>

<li><var>fontsize</var> =&gt; <code>(point <var>n</var>)</code>. Gives the size of <var>n</var> points. <var>n</var>
must convert to a floating-point number.</li>

<li><var>fontsize</var> =&gt; <code>(pixel <var>n</var>)</code>. Gives the size of <var>n</var> pixels. <var>n</var>
must convert to a floating-point number.</li>

<li><var>fontsize</var> =&gt; <code>(inch <var>n</var>)</code>. Gives the size of <var>n</var> inches. <var>n</var>
must convert to a floating-point number.</li>

<li><var>fontsize</var> =&gt; <code>(millimeter <var>n</var>)</code>. Gives the size of <var>n</var>
millimeters. <var>n</var> must convert to a floating-point number.</li>

</ulp>

</section>

<section name="byterect"><title>Byte Rectangle Functions</title>

<p>Byte rectangles, or <i>byterects</i>, represent rectangular regions within byte arrays. A byte rectangle groups
five components:</p>

<ul>

<li>The byte array in which the rectangle is located</li>

<li>The offset into the byte array</li>

<li>The width of the rectangle</li>

<li>The height of the rectangle</li>

<li>The <i>stride</i> of the rectangle, which is the distance from the beginning of any line to the beginning of the
next line.</li>

</ul>

<p>Byte rectangles are used by the following functions.</p>

<ulp>

<li><code>(byterect? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a byterect,
and <code>#f</code> otherwise.</li>

<li><code>(make-byterect <var>arr</var> <var>offset</var> <var>width</var> <var>height</var> <var>stride</var>)</code>. Creates
a byterect with the given parameters.</li>

<li><code>(byterect-valid? <var>byterect</var>)</code>. Returns <code>#t</code> if all the bytes in the rectangle are
actually located within the byte array, and <code>#f</code> otherwise.</li>

<li><code>(byterect-get-line <var>line</var>)</code>. Returns a line from a byterect as a byterange.</li>

<li><code>(get-byterect-array <var>byterect</var>)</code>. Gets the array component of <var>byterect</var>.</li>

<li><code>(get-byterect-offset <var>byterect</var>)</code>. Gets the offset component of <var>byterect</var>.</li>

<li><code>(get-byterect-width <var>byterect</var>)</code>. Gets the width component of <var>byterect</var>.</li>

<li><code>(get-byterect-height <var>byterect</var>)</code>. Gets the height component of <var>byterect</var>.</li>

<li><code>(get-byterect-stride <var>byterect</var>)</code>. Gets the stride component of <var>byterect</var>.</li>

<li><code>(copy-byterect! <var>src</var> <var>dest</var>)</code>. Copies bytes from the source byterect to the
destination byterect. Both byterects must be the same width and the same height, but the origin and strides can be
different. Copying is <i>not</i> necessarily handled correctly if the source and destination overlap.</li>

<li><code>(fill-byterect! <var>dest</var> <var>byte</var>)</code>. Fills the given byterect with copies of the given
byte.</li>

<li><code>(make-bitmap-maker <var>widthExpr</var> <var>heightExpr</var> <var>copyBitsExpr</var>)</code>. Creates a
function <var>func</var> with the signature <code>(<var>func</var> <var>pixels</var> <var>palette</var>)</code>. The
expressions must be in Pascalesque notation (described in <xref dest="pascalesque"/>). The <var>widthExpr</var>
and <var>heightExpr</var> will be compiled in an environment where a variable called <code>pixels</code> of
type <code>byterect</code> is defined; these expressions must evaluate to integers giving the size of the output
bitmap. <var>copyBitsExpr</var> will be compiled in an environment where <code>pixels</code> of
type <code>byterect</code>, <code>palette</code> of type <code>(array-of int)</code>, and <code>lockedBits</code> of
type <code>bitmapdata</code> are all defined. <var>copyBitsExpr</var> must evaluate to type <code>void</code>.</li>

</ulp>

</section>

<section name="fonts"><title>Font Functions</title>

<p>These functions allow the use of fonts on the system.</p>

<ulp>

<li><code>(fontstyle <var>list</var>)</code>. Creates and returns a font style from the symbols in the list, which
must include zero or more of (<code>bold</code> or <code>b</code>), (<code>italic</code>, <code>italics</code>,
or <code>i</code>), (<code>strikethrough</code>, <code>strikeout</code>, or <code>s</code>), or
(<code>underline</code> or <code>u</code>).  The symbols that are grouped together are synonymous. Other symbols are
ignored.</li>

<li><code>(fontstyle? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a font style, and
<code>#f</code> otherwise.</li>

<li><code>(fontstyle-&gt;list <var>fontstyle</var>)</code>. Creates a list of symbols representing the font styles in
the font style object <var>fontstyle</var>. This is the inverse of the <code>fontstyle</code> function.</li>

<li><code>(make-font <var>name</var> <var>size</var> <var>fontstyle</var>)</code>.  Creates and returns a font object
given its <var>name</var> as a string, its <var>size</var> as a floating-point number, and its <var>fontstyle</var> as
a font style object. Returns a font object.</li>

<li><code>(font-get-height <var>font</var>)</code>. Returns the height of the font.</li>

<li><code>(font-get-cell-ascent <var>font</var>)</code>. Returns the cell ascent of the font.</li>

<li><code>(font-get-em-height <var>font</var>)</code>. Returns the &ldquo;M&rdquo; height of the font.</li>

<li><code>(font-get-line-spacing <var>font</var>)</code>. Returns the default line spacing appropriate for the
font.</li>

<li><code>(font-is-style-available? <var>font</var> <var>fontstyle</var>)</code>. Returns <code>#t</code> if it is
possible to make a variant of the font <var>font</var> with the style <var>fontstyle</var>, and <code>#f</code>
otherwise.</li>

<li><code>(graphics-draw-text! <var>graphics</var> <var>string</var> <var>font</var> <var>brush</var> <var>pointf</var>)</code>.
Draws <var>string</var> on <var>graphics</var>, using <var>font</var> and <var>brush</var>, at the given point.</li>

<li><code>(graphics-measure-text! <var>graphics</var> <var>string</var> <var>font</var> <var>proc</var>)</code>.
Calculates the size of <var>string</var> when rendered with <var>font</var> and passes it to <var>proc</var>,
tail-calling <code>(<var>proc</var> <var>width</var> <var>height</var>)</code>.</li>

</ulp>

</section>

<section name="windowing"><title>Windowing Functions</title>

<p>These functions allow the use of a window.</p>

<ulp>

<li><code>(make-window <var>xsize</var> <var>ysize</var>)</code>. Create a new window with the given dimensions.</li>

<li><code>(make-window-from-bitmap <var>bitmap</var>)</code>. Create a new window with the given initial bitmap.</li>

<li><code>(set-window-image! <var>window</var> <var>bitmap</var>)</code>. Sets the window&rsquo;s content to the given
bitmap. The window is resized if necessary.</li>

<li><code>(get-window-pixel-format <var>window</var>)</code>. Requests the window&rsquo;s current pixel format.  The
window will post its pixel format in its message queue. (The pixel format is somewhat useless because the bitmap
functions in this Scheme always use the same pixel format.)</li>

<li><code>(window-sync! <var>window</var> <var>andmask</var> <var>xormask</var>)</code>. <var>andmask</var>
and <var>xormask</var> must be dot-Net enumeration values of the
type <code>ControlledWindowLib.EventTypes</code>. This causes the window to post a sync message to its queue. This
function returns a guid that can be used to identify the sync message when it is later read out of the queue. Syncing
allows you to discard all messages up to the present. It also allows you to select what kinds of messages you want to
receive in the future. The existing event-types bits are anded with the <var>andmask</var> and then xored with
the <var>xormask</var>. The sync message will include the old event types and the new event types.</li>

<li><code>(begin-get-window-event <var>window</var>)</code>. Starts an asynchronous operation which retrieves the next
message from the window, and returns its asynchronous ID.</li>

</ulp>

<p>The messages from <code>begin-get-window-event</code> are all hash maps. They all contain a type member, and some of
them contain other members.</p>

<ulp>

<li><code>#m((type . closed))</code> indicates that the window was closed. If the window is closed, this is the last
message you will receive from it. You cannot ever filter out this message.</li>

<li><code>#m((type . got-focus))</code> indicates that the window got the keyboard focus.</li>

<li><code>#m((type . lost-focus))</code> indicates that the window lost the keyboard focus.</li>

<li><code>#m((type . mouse-enter))</code> indicates that the mouse entered the window.</li>

<li><code>#m((type . mouse-leave))</code> indicates that the mouse left the window.</li>

<li><code>#m((type . timer-tick))</code> indicates that the window&rsquo;s timer ticked.</li>

<li><code>#m((type . key-down) (key-data . <var>k</var>))</code> indicates that a key was pressed. <var>k</var> is an
enumeration of the type <code>System.Windows.Forms.Keys</code> that indicates which key was pressed.</li>

<li><code>#m((type . key-up) (key-data . <var>k</var>))</code> indicates that a key was released. <var>k</var> is an
enumeration of the type <code>System.Windows.Forms.Keys</code> that indicates which key was released.</li>

<li><code>#m((type . key-press) (char . <var>char</var>))</code> indicates that a keypress generated a character.
<var>char</var> is the character that was generated.</li>

<li><code>#m((type . mouse-down) (x . <var>x</var>) (y . <var>y</var>) (buttons . <var>buttons</var>))</code>
indicates that a mouse button was pressed (and is still down). <var>x</var> and <var>y</var> indicate the coordinates
at which the click began. <var>buttons</var> is an enumeration of the
type <code>System.Windows.Forms.MouseButtons</code> which indicates which mouse buttons were involved.</li>

<li><code>#m((type . mouse-up) (x . <var>x</var>) (y . <var>y</var>) (buttons . <var>buttons</var>))</code> indicates
that a mouse button was released. <var>x</var> and <var>y</var> indicate the coordinates at which the release
occurred. <var>buttons</var> is an enumeration of the type <code>System.Windows.Forms.MouseButtons</code> which
indicates which mouse buttons were involved.</li>

<li><code>#m((type . mouse-move) (x . <var>x</var>) (y . <var>y</var>))</code> indicates that the mouse moved.
<var>x</var> and <var>y</var> indicate the position it moved to.</li>

<li><code>#m((type . pixel-format) (pixel-format . <var>format</var>))</code> indicates that the window has
returned its pixel format after a call to <code>get-window-pixel-format</code>. <var>format</var> is an enumeration
of type <code>System.Drawing.Imaging.PixelFormat</code>.</li>

<li><code>#m((type . sync) (id . <var>id</var>) (event-types . <var>flags</var>) (old-event-types
. <var>oldflags</var>))</code> is the sync message generated by a call to <code>window-sync!</code>. <var>flags</var>
and <var>oldflags</var> indicate the current and previous set of flags which indicate which messages are being
received or were being received. They are enumerations of type <code>ControlledWindowLib.EventTypes</code>.</li>

</ulp>

</section>

<section name="windowing_obj"><title>Window Object Functions</title>

<p>These functions allow the creation of window objects.</p>

<ulp>

<li><code>(make-window-obj <var>xsize</var> <var>ysize</var>)</code>. Creates a window object of the given dimensions
and returns its Object ID.</li>

<li><code>(make-window-obj-from-bitmap <var>bitmap</var>)</code>. Creates a window object with the
given <var>bitmap</var> and returns its Object ID.</li>

</ulp>

<p>Window objects are controlled by posting messages to them.</p>

<ulp>

<li><code>#sig(set-title . title)</code>. Sets the title of the window to <code>title</code>, which must be a string.</li>

<li><code>#sig(set-image . image)</code>. Sets the window to display <code>image</code>, which must be the
Disposable ID of a bitmap. The window will resize itself if necessary.</li>

<li><code>#sig(draw . drawing)</code>. Draws <code>drawing</code> on the window. <code>drawing</code> must be in the
drawing language used by the <code>graphics-draw!</code> function.</li>

<li><code>#sig(sync . andmask xormask)</code>. Posts a synchronization message to the window. <code>andmask</code> and
<code>xormask</code> must be enumerations of type <code>ControlledWindowLib.EventTypes</code>. The current set of
event types will be anded with <code>andmask</code> and then xored with <code>xormask</code> to produce the new set of
event types.</li>

<li><code>#sig(set-dest . k kdata)</code>. Sets the destination to which the window will post its messages. The window
posts messages when things happen to it such as key presses and mouse clicks. <code>k</code> should be the Object ID
of the destination. <code>kdata</code> is just a piece of data which is copied into every message posted and can be
used to identify the window (if multiple windows are posting to the same destination).</li>

</ulp>

<p>The messages that the window posts will match these signatures.</p>

<ulp>

<li><code>#sig(closed . kdata)</code>. The window closed.</li>

<li><code>#sig(exception . exception kdata)</code>. An exception was thrown. Right now, this is only sent if a Sync
operation fails for some reason.</li>

<li><code>#sig(goodbye . kdata)</code>. Messages from the window have been directed elsewhere.</li>

<li><code>#sig(got-focus . kdata)</code>. The window received the keyboard focus.</li>

<li><code>#sig(hello . kdata)</code>. Messages from the window are now being directed here (to the receiver of this
message).</li>

<li><code>#sig(key-down . kdata keydata)</code>. A key went down. The <code>keydata</code> value is of type
<code>System.Windows.Forms.Keys</code>.</li>

<li><code>#sig(key-press . kdata char)</code>. A character was typed. The <code>char</code> value is the character
typed.</li>

<li><code>#sig(key-up . kdata keydata)</code>. A key went up. The <code>keydata</code> value is of type
<code>System.Windows.Forms.Keys</code>.</li>

<li><code>#sig(lost-focus . kdata)</code>. The window lost the keyboard focus.</li>

<li><code>#sig(mouse-down . kdata x y buttons)</code>. A mouse button went down. The <code>x</code> and <code>y</code>
values are the co-ordinates of the location where the mouse was clicked. The <code>buttons</code> value is of type
<code>System.Windows.Forms.MouseButtons</code> and indicates which buttons went down.</li>

<li><code>#sig(mouse-enter . kdata)</code>. The mouse entered the window.</li>

<li><code>#sig(mouse-leave . kdata)</code>. The mouse left the window.</li>

<li><code>#sig(mouse-move . kdata x y)</code>. The mouse moved. The <code>x</code> and <code>y</code> values are
the co-ordinates of the location of the mouse.</li>

<li><code>#sig(mouse-up . kdata x y buttons)</code>. A mouse button went up. The <code>x</code> and <code>y</code>
values are the co-ordinates of the location where the mouse button went up. The <code>buttons</code> value is of
type <code>System.Windows.Forms.MouseButtons</code> and indicates which buttons went up.</li>

<li><code>#sig(pixel-format . kdata pixel-format)</code>. This message is a response to a request to get the pixel
format. (There is currently no way to issue such a request.) <code>pixel-format</code> is a value of
type <code>System.Drawing.Imaging.PixelFormat</code>.</li>

<li><code>#sig(sync . kdata id old-event-types event-types)</code>. This message is a response to a <code>sync</code>
message. <code>id</code> is a GUID identifying the sync request. <code>old-event-types</code> is a value of
type <code>ControlledWindowLib.EventTypes</code> indicating what event types used to generate messages before the
<code>sync</code> was processed. <code>event-types</code> is a value of the same type which indicates what event
types will generate messages henceforth.</li>

<li><code>#sig(sync-posted . id kdata)</code>. A <code>sync</code> message was posted to the window.
Its <code>id</code> is given by a GUID.</li>

<li><code>#sig(timer . kdata)</code>. A timer event occurred.</li>

<li><code>#sig(unknown . kdata)</code>. An unknown event occurred.</li>

</ulp>

</section>

<section name="logwindow"><title>Log Window Functions</title>

<p>A log window simply displays every message that is posted to it. The user can copy messages to the clipboard. This
is primarily useful for debugging.</p>

<ulp>

<li><code>(make-log-window)</code>. Creates a new log window and returns its Object ID.</li>

</ulp>

</section>

<section name="filesys"><title>File System Access Functions</title>

<p>These functions deal with files and directories.</p>

<ulp>

<li><code>(file-exists? <var>file</var>)</code>. Returns <code>#t</code> if <var>file</var> exists and is a file, and
<code>#f</code> otherwise. <var>file</var> can be a string containing the name of the file, or it can be a file
object.</li>

<li><code>(directory-exists? <var>dir</var>)</code>. Returns <code>#t</code> if <var>dir</var> exists and is a
directory, and <code>#f</code> otherwise. <var>dir</var> can be a string containing the name of the directory, or it
can be a directory object.</li>

<li><code>(get-desktop)</code>. Returns a string containing the path to the desktop of the user currently logged
in.</li>

<li><code>(list-directory <var>dir</var>)</code>. Returns a list of the file and directory objects that represent the
contents of the directory <var>dir</var>. <var>dir</var> can be a string containing the name of the directory, or it
can be a directory object.</li>

<li><code>(is-fsi? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a <code>FileSystemInfo</code>
object, and <code>#f</code> otherwise.</li>

<li><code>(fsi-is-directory? <var>fsi</var>)</code>. Returns <code>#t</code> if <var>fsi</var> is a
<code>DirectoryInfo</code> object, and <code>#f</code> otherwise.</li>

<li><code>(fsi-is-file? <var>fsi</var>)</code>. Returns <code>#t</code> if <var>fsi</var> is a <code>FileInfo</code>
object, and <code>#f</code> otherwise.</li>

<li><code>(fsi-get-name <var>fsi</var>)</code>. Returns, as a string, the name of the file represented by the
<code>FileSystemInfo</code> <var>fsi</var>.</li>

<li><code>(fsi-get-length <var>fsi</var>)</code>. Returns the length of the file represented by the
<code>FileSystemInfo</code> <var>fsi</var>.</li>

</ulp>

</section>

<section name="binfiles"><title>File I/O Functions</title>

<p>Here are the file I/O functions.</p>

<ulp>

<li><code>(slurp-bytes <var>obj</var>)</code>. <var>obj</var> can be a <code>FileSystemInfo</code> object or a
string. Opens the file named by <var>obj</var>, reads the entire file into a byte array, and returns the byte
array. The byte array will be set to low-byte low-address mode.</li>

<li><code>(slurp-lines <var>obj</var>)</code>. <var>obj</var> can be a <code>FileSystemInfo</code> object or a
string. Opens the UTF8 text file named by <var>obj</var>, reads the entire file into a vector of strings, and returns
the vector. Each line in the file will become a string in the vector.</li>

<li><code>(slurp-data <var>obj</var>)</code>. <var>obj</var> can be a <code>FileSystemInfo</code> object or a
string. Opens the UTF8 file named by <var>obj</var>, interprets the file with the Scheme lexer, and returns a list of
the resulting Scheme objects.</li>

<li><code>(byte-copy-with-files! <var>src</var> <var>srcoff</var> <var>len</var> <var>dest</var>
<var>destoff</var>)</code>. <var>src</var> and <var>dest</var> can be Scheme byte arrays or filenames or
<code>FileSystemInfo</code> objects. Copies <var>len</var> bytes from offset <var>srcoff</var> in the source
to offset <var>destoff</var> in the destination.</li>

<li><code>(eof)</code>. Returns the EOF object.</li>

<li><code>(eof? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is the EOF object, and
<code>#f</code> otherwise.</li>

</ulp>

<p>There are also functions to deal with streams. These offer asynchronous byte-buffer I/O.</p>

<ulp>

<li><code>(make-file-stream-reader <var>filename</var>)</code>. Creates a disposable stream that can read from the
file named by <var>filename</var>. The file must exist and you must have permission.</li>

<li><code>(make-file-stream-writer <var>filename</var>)</code>. Creates a disposable stream that can write to the file
named by <var>filename</var>. The file will be replaced and you must have permission to do so.</li>

<li><code>(make-file-stream-reader-writer <var>filename</var>)</code>. Creates a disposable stream that can read or
write to the file named by <var>filename</var>. The file will be created if it does not exist, and you must have
permission to create or access it.</li>

<li><code>(stream? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a stream, and
<code>#f</code> otherwise.</li>

<li><code>(stream-can-seek? <var>stream</var>)</code>. Returns <code>#t</code> if the stream is seekable
and <code>#f</code> otherwise. All file streams are seekable.</li>

<li><code>(stream-position <var>stream</var>)</code>. Retrieves the current position of the given stream.</li>

<li><code>(stream-set-position! <var>stream</var>)</code>. Sets the position in the given stream and returns the
unspecified value.</li>

<li><code>(stream-length <var>stream</var>)</code>. Retrieves the size of the current stream.</li>

<li><code>(stream-set-length! <var>stream</var>)</code>. Sets the size of the current stream and returns the
unspecified value.</li>

<li><code>(begin-stream-read! <var>stream</var> <var>byterange</var>)</code>. Begins an asynchronous operation which
will read bytes from the stream and store them in the given byte range. This function reads as many bytes as are
necessary to fill the range. The file position is advanced immediately, which means you can issue a second
asynchronous read (or write) before this operation has completed. Returns an asynchronous ID.</li>

<li><code>(begin-stream-write! <var>stream</var> <var>byterange</var>)</code>. Begins an asynchronous operation which
will write bytes from given byte range into the stream at the current file position. The file position is advanced
immediately, which means you can issue a second asynchronous write (or read) before this operation has
completed. Returns an asynchronous ID.</li>

</ulp>

</section>

<section name="networking"><title>Networking Functions</title>

<p>Sunlit World Scheme now offers several functions to perform networking operations.</p>

<ulp>

<li><code>(ipaddr <var>obj</var>)</code>. Converts <var>obj</var> to an IP address. <var>obj</var>
must be a string containing an IPv4 or IPv6 network address; it cannot be a hostname. <var>obj</var>
can also be one of the symbols <code>any</code>, <code>broadcast</code>, <code>none</code>,
<code>loopback</code>, <code>v6any</code>, <code>v6none</code>, or <code>v6loopback</code>.</li>

<li><code>(begin-dns-lookup <var>name</var>)</code>. Starts an asynchronous
operation to retrieve the IP addresses of the machine with the given DNS name. They will be returned
as a list.</li>

<li><code>(ipaddr-&gt;string <var>ipaddr</var>)</code>. Converts the given IP address to a string.</li>

</ulp>

</section>

<section name="udp"><title>User Datagram Functions</title>

<ulp>

<li><code>(open-udp <var>ipaddr</var> <var>port</var>)</code>. Creates a UDP socket. UDP sockets
are disposable.</li>

<li><code>(begin-udp-receive <var>udpsocket</var>)</code>. Begins an asynchronous operation which will wait for a UDP
packet and then return it. This function returns a hash map of the form <code>#m((address . <var>srcaddress</var>)
(port . <var>srcport</var>) (data . <var>bytearray</var>))</code>.</li>

<li><code>(udp-send! <var>udpsocket</var> <var>destaddr</var> <var>destport</var>
<var>byterange</var>)</code>. Sends the given byte range as a single packet to the given destination address and port,
using the given UDP socket.</li>

</ulp>

</section>

<section name="tcp"><title>TCP Streaming Functions</title>

<ulp>

<li><code>(make-tcp-server <var>localaddress</var> <var>port</var> <var>backlog</var>)</code>. Creates a TCP
server socket, which is disposable. <var>localaddress</var> and <var>port</var> should be the local address and
port on which it should listen. <var>backlog</var> indicates how many pending connections the implementation
should keep track of.</li>

<li><code>(begin-tcp-accept! <var>serversocket</var>)</code>. Begins an asynchronous operation that waits for a
connection on <var>serversocket</var> and returns a socket that can be used to communicate with the client.</li>

<li><code>(begin-tcp-connect! <var>remoteaddr</var> <var>port</var>)</code>. Begins an asynchronous operation which
attempts to connect to a remote TCP server socket. Returns the socket if successful.</li>

<li><code>(begin-tcp-send! <var>socket</var> <var>byterange</var>)</code>. Begins an asynchronous operation which
attempts to send all the bytes from <var>byterange</var> on socket <var>socket</var>. Returns the number of bytes
actually sent.</li>

<li><code>(begin-tcp-receive! <var>socket</var> <var>byterange</var>)</code>. Begins an asynchronous operation which
attempts to receive enough bytes on <var>socket</var> to fill the byte range. Returns the number of bytes actually
read.</li>

</ulp>

</section>

<section name="async_queues"><title>Asynchronous Queue Functions</title>

<p>Asynchronous queues are used to send messages from one thread to another. A thread can
call <code>begin-async-queue-get!</code> to receive messages to itself. Other threads can send it messages by
calling <code>async-queue-put!</code>.</p>

<p>First is the function to create an asynchronous queue.</p>

<ulp>

<li><code>(make-async-queue)</code>. Creates a new asynchronous queue. Asynchronous queues are disposable. If the
asynchronous queue is disposed while a thread is waiting on it, the thread will receive
an <code>ObjectDisposedException</code>.</li>

</ulp>

<p>The following functions are used by the sending side.</p>

<ulp>

<li><code>(async-queue-put! <var>aqueue</var> <var>obj</var>)</code>. Inserts <var>obj</var> into the asynchronous
queue <var>aqueue</var>. Returns the unspecified value.</li>

<li><code>(async-queue-close! <var>aqueue</var>)</code>. Closes the asynchronous queue <var>aqueue</var> and returns
the unspecified value. Once a queue is closed, it is no longer possible to put messages into it; any attempt to do so
will throw an exception of type <code>ControlledWindowLib.AsyncQueueClosedException</code>.</li>

<li><code>(async-queue-closed? <var>aqueue</var>)</code>. Returns <code>#t</code> if the asynchronous
queue <var>aqueue</var> is closed and <code>#f</code> otherwise.</li>

</ulp>

<p>The following functions are used by the receiving side.</p>

<ulp>

<li><code>(begin-async-queue-get! <var>tqueue</var>)</code>. Begins an asynchronous operation to retrieve the next
item in the asynchronous queue. If there are already one or more items queued, the asynchronous operation will succeed
immediately, returning the oldest item. If not, the operation will not complete until (a) some other thread posts an
item to the queue, in which case it will be returned, or (b) some other thread closes the queue, in which case
the <code>AsyncQueueClosedException</code> is raised, or (c) some other thread disposes the queue, in which case
a <code>System.ObjectDisposedException</code> is raised.</li>

<li><code>(async-queue-empty? <var>aqueue</var>)</code>. Returns <code>#t</code> if the next attempt to get something
is guaranteed to return an <code>AsyncQueueClosedException</code>.</li>

<li>The receiving side is responsible for calling <code>(dispose! <var>aqueue</var>)</code> when the queue is
empty.</li>

</ulp>

<p>The following functions are used for error handling.</p>

<ulp>

<li><code>(async-queue-closed-exception? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is
an <code>AsyncQueueClosedException</code>, and <code>#f</code> otherwise.</li>

<li><code>(object-disposed-exception? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is
an <code>ObjectDisposedException</code>, and <code>#f</code> otherwise.</li>

</ulp>

<p>Although it is not possible for two threads to await the same get operation, it is possible for two separate get
operations to be issued against the same asynchronous queue. If two or more separate get operations are issued against
an asynchronous queue, the oldest one will be fulfilled first. It is rare to have multiple outstanding gets on the
same queue, because it is not usually possible for the sender to tell how many get operations are outstanding or which
get operation will receive the next message. However, there are some applications where it does not matter. For
example, you could be sending jobs to a thread pool. Every non-busy thread in the pool can call <code>get</code> on
the same queue, because the job will be treated the same way regardless of which thread receives it.</p>

<p>Code usually has to be written under the assumption that any <code>get</code> operation may throw
an <code>AsyncQueueClosedException</code>. Checking for the exception is usually not difficult, because of the
way <code>wait-any</code> returns asynchronous exceptions, but it is something to be aware of.</p>

<p>The <code>is-empty</code> function does not create such a race condition, because it only returns <code>#t</code>
if the asynchronous queue is already closed.</p>

<p>It is generally a bad practice for the sender to call <code>dispose!</code> on an asynchronous queue. The sender
should call <code>close!</code> instead. The receiver can then handle any items that are still in the queue and then
dispose the queue itself, when it&rsquo;s empty.</p>

</section>

<section name="timer_queues"><title>Timer Queues</title>

<p>Timer Queues are similar to asynchronous queues, but you can specify a delay when you post a message to the
queue. The message will not arrive until after the delay has passed. Although a thread can use a timer queue to
communicate with other threads, it is more common for a thread to use a timer queue to communicate with itself. A
typical usage is to receive notification when some other operation has &ldquo;timed out.&rdquo;</p>

<p>Timer queues are more expensive than asynchronous queues. A timer queue creates a worker thread that handles
dispatching messages when their due time arrives. An asynchronous queue does not have a worker thread.</p>

<ulp>

<li><code>(make-timer-queue)</code>. Creates a new timer queue. Timer queues are disposable.</li>

<li><code>(timer-queue-put! <var>tqueue</var> <var>delay</var> <var>obj</var>)</code>. Inserts <var>obj</var>
into the timer queue <var>tqueue</var>. It will appear after a delay of approximately <var>delay</var>
milliseconds. Returns the unspecified value.</li>

<li><code>(begin-timer-queue-get! <var>tqueue</var>)</code>. Begins an asynchronous operation to retrieve the next
item in the timer queue. This operation will not complete until the item&rsquo;s scheduled time arrives, or the queue
is disposed. If the queue is disposed, the result is an <code>ObjectDisposedException</code>.</li>

<li><code>(get-tick-count)</code>. Returns the least significant 32 bits of the number of milliseconds
since Windows started running. The return value may only be accurate to within 15 milliseconds or so.</li>

</ulp>

</section>

<section name="cryptography"><title>Cryptography Functions</title>

<p>Sunlit World Scheme provides a wrapper around some of the dot-Net cryptography functions. This makes it easy to use
both conventional and public-key cryptography.</p>

<ulp>

<li><code>(begin-make-akey <var>encrypt</var> <var>sign</var>)</code>. Starts an asynchronous operation which
generates an asymmetric key useful for public-key cryptography. <var>encrypt</var> should be a boolean indicating
whether you want the key to support encryption and decryption. <var>sign</var> should be a boolean indicating whether
you want the key to support creating and verifying signatures. One of these booleans must be true. Both the public and
private parts of the key are generated and returned.</li>

<li><code>(akey? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is an asymmetric key
and <code>#f</code> if not.</li>

<li><code>(akey-can-encrypt? <var>akey</var>)</code>. Returns <code>#t</code> if <var>akey</var> can be used to
encrypt, and <code>#f</code> if it cannot.</li>

<li><code>(akey-can-decrypt? <var>akey</var>)</code>. Returns <code>#t</code> if <var>akey</var> can be used to
decrypt, and <code>#f</code> if it cannot.</li>

<li><code>(akey-can-verify? <var>akey</var>)</code>. Returns <code>#t</code> if <var>akey</var> can be used to verify
a signature, and <code>#f</code> if it cannot.</li>

<li><code>(akey-can-sign? <var>akey</var>)</code>. Returns <code>#t</code> if <var>akey</var> can be used to generate
a signature, and <code>#f</code> if it cannot.</li>

<li><code>(akey-get-public <var>akey</var>)</code>. Returns the public portion of an asymmetric key <var>akey</var>.
If the input key can encrypt and decrypt, the output key can only encrypt; if the input key can sign and verify, the
output key can only verify.</li>

<li><code>(akey-encrypt <var>akey</var> <var>data</var>)</code>. Encrypts <var>data</var> with <var>akey</var> and
returns the ciphertext. <var>data</var> must be a byte array, and the return value is a byte array.</li>

<li><code>(akey-decrypt <var>akey</var> <var>ciphertext</var>)</code>. Decrypts <var>ciphertext</var>, which must be
a byte array, with <var>akey</var> and returns the resulting plaintext.</li>

<li><code>(akey-verify <var>akey</var> <var>data</var> <var>signature</var>)</code>. Returns <code>#t</code> if the
byte array <var>signature</var> is a valid signature for the byte array <var>data</var> with the
given <var>akey</var>, and <code>#f</code> if not.</li>

<li><code>(akey-sign <var>akey</var> <var>data</var>)</code>. Creates a digital signature for the byte
array <var>data</var> and returns it as a byte array.</li>

<li><code>(akey-&gt;bytes <var>akey</var>)</code>. Converts an asymmetric key <var>akey</var> to a specially-formatted
byte array.</li>

<li><code>(bytes-&gt;akey <var>bytes</var>)</code>. Converts the specially formatted byte array <var>bytes</var> to an
asymmetric key.</li>

<li><code>(make-ckey <var>bits</var> <var>password?</var>)</code>. Creates a conventional key. <var>bits</var> must be
one of the integers <code>128</code>, <code>192</code>, or <code>256</code>. <var>password</var> is optional; if it is
provided, it must be a string, byte array, or integer. If <var>password</var> is provided, it is hashed using SHA 384,
and this is used to produce the conventional key. If <var>password</var> is not provided, a random key is
generated.</li>

<li><code>(ckey? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a conventional key,
and <code>#f</code> otherwise.</li>

<li><code>(ckey-encrypt <var>ckey</var> <var>data</var>)</code>. Encrypts the byte array <var>data</var> with the
given conventional key and returns the ciphertext as a byte array.</li>

<li><code>(ckey-decrypt <var>ckey</var> <var>ciphertext</var>)</code>. Decrypts the byte array <var>ciphertext</var>
with the given conventional key and returns the plaintext as a byte array.</li>

<li><code>(ckey-&gt;bytes <var>ckey</var>)</code>. Converts a conventional key <var>ckey</var> to a specially-formatted
byte array.</li>

<li><code>(bytes-&gt;ckey <var>bytes</var>)</code>. Converts a specially formatted byte array to a conventional
key.</li>

<li><code>(sha384 <var>data</var>)</code>. Finds the SHA 384 hash of <var>data</var>. <var>data</var> can be a byte
array, a string, or an integer.</li>

</ulp>

</section>

<section name="reflection"><title>Reflection Functions</title>

<p>These functions allow reflection over all the dot-Net types currently loaded.</p>

<ulp>

<li><code>(type <var>name</var>)</code>. Finds the dot-Net type whose name is the string <var>name</var>, and returns
the <code>System.Type</code> object. (For example, the name can be something
like <code>System.Collections.Generic.List`1</code>.) Throws an exception if the type is not found.</li>

<li><code>(is-open-generic-type? <var>type</var>)</code>. Returns <code>#t</code> if <var>type</var> is a generic type
with the parameter types unspecified, and <code>#f</code> if it represents any other kind of type. Throws an exception
if the argument is not a <code>System.Type</code> object.</li>

<li><code>(is-open-generic-method? <var>methodinfo</var>)</code>. Returns <code>#t</code> if <var>methodinfo</var> is
a generic method with the parameter types unspecified, and <code>#f</code> if it represents any other kind of
type. Throws an exception if the argument is not a <code>System.Type</code> object.</li>

<li><code>(count-generic-type-parameters <var>type</var>)</code>. Returns the number of unspecified generic type
parameters in <var>type</var>.</li>

<li><code>(count-generic-method-parameters <var>methodinfo</var>)</code>. Returns the number of unspecified generic
type parameters in <var>methodinfo</var>.</li>

<li><code>(is-enum? <var>type</var>)</code>. Returns <code>#t</code> if <var>type</var> is an enumeration type,
and <code>#f</code> if it represents any other kind of type. Throws an exception if the argument is not
a <code>System.Type</code> object.</li>

<li><code>(is-enum-flags? <var>type</var>)</code>. Returns <code>#t</code> if <var>type</var> is an enumeration type
with the &ldquo;flags&rdquo; attribute, and <code>#f</code> if it represents any other kind of type, including a
non-flags enumeration type. Throws an exception if the argument is not a
<code>System.Type</code> object.</li>

<li><code>(get-enum-values <var>type</var>)</code>. Returns a list of the values that are defined for a dot-Net
enumeration. Each item in the list is a pair of the form <code>(<var>symbol</var> . <var>value</var>)</code>,
where <var>symbol</var> is case-sensitive and <var>value</var> is an integer.</li>

<li><code>(enum-value <var>type</var> <var>symbol</var>)</code>. Returns the integer value of an enumeration
symbol. The symbol must be defined in the enumeration.</li>

<li><code>(enum-&gt;integer <var>value</var>)</code>. <var>value</var> must be a value of a dot-Net enumeration. This
function returns its value as an integer.</li>

<li><code>(integer-&gt;enum <var>type</var> <var>int</var>)</code>. Returns the dot-Net enumeration value that
corresponds to the given integer.</li>

<li><code>(field <var>type</var> <var>name</var>)</code>. Returns the <code>System.Reflection.FieldInfo</code> object
for the field of the type <var>type</var> whose name is the string <var>name</var>. Throws an exception if the field
is not found.</li>

<li><code>(is-static-field? <var>field</var>)</code>. Returns <code>#t</code> if <var>field</var> represents a static
field, and <code>#f</code> otherwise. Throws an exception if <var>field</var> is not
a <code>System.Reflection.FieldInfo</code> object.</li>

<li><code>(static-field-ref <var>field</var>)</code>. Fetches the value of the static field <var>field</var>.</li>

<li><code>(static-field-set! <var>field</var> <var>obj</var>)</code>. Stores <var>obj</var> in the static
field <var>field</var>.</li>

<li><code>(field-ref <var>obj</var> <var>field</var>)</code>. Fetches the field <var>field</var> from the
object <var>obj</var>.</li>

<li><code>(field-set! <var>obj</var> <var>field</var> <var>val</var>)</code>. Stores <var>val</var> in the
field <var>field</var> of the object <var>obj</var>.</li>

<li><code>(method <var>type</var> <var>name</var> <var>param</var> <var>...</var>)</code>. Retrieves the method
of <var>type</var> with the given name (<var>name</var> must be a string) and parameters (which must be types).</li>

<li><code>(is-static-method? <var>method</var>)</code>. Returns <code>#t</code> if <var>method</var> represents a
constructor or a static method, and <code>#f</code> if it represents an instance method. Throws an exception
if <var>method</var> is not a method.</li>

<li><code>(generic-type <var>opengenerictype</var> <var>type1</var> <var>...</var>)</code>. Specifies the type
parameters for an open generic type, returning a closed generic type.</li>

<li><code>(generic-method <var>opengenericmethod</var> <var>type1</var> <var>...</var>)</code>. Specifies the type
parameters for an open generic method, returning a closed generic method.</li>

<li><code>(constructor <var>type</var> <var>param</var> <var>...</var>)</code>. Retrieves the constructor for
type <var>type</var> with the given parameters (which must be types). The constructor can be treated as a static
method.</li>

<li><code>(invoke <var>obj</var> <var>method</var> <var>arg1</var> <var>...</var>)</code>. Invokes the instance
method <var>method</var> on the instance <var>obj</var>, with the given arguments. You must specify the same
number of arguments that the method actually expects.</li>

<li><code>(static-invoke <var>method</var> <var>arg1</var> <var>...</var>)</code>. Invokes the static method
or constructor <var>method</var> with the given arguments. You must specify the same number of arguments that
the static method or constructor actually expects.</li>

</ulp>

</section>

<section name="func_eval"><title>Nested Interpreter Functions</title>

<p>This is my attempt to make up for not having macros.</p>

<p>All top-level objects share the same global state. This means that top-level objects can see each other&rsquo;s
disposable objects and asynchronous operations.</p>

<ulp>

<li><code>(make-top-level)</code>. Creates a new top-level object.</li>

<li><code>(top-level? <var>obj</var>)</code>. Returns <code>#t</code> if <var>obj</var> is a top-level object,
otherwise returns <code>#f</code>.</li>

<li><code>(eval <var>toplevel</var> <var>expr</var>)</code>. Expects <var>expr</var> to evaluate to a valid Scheme
expression or top-level form. Evaluates it in the given <var>toplevel</var>, which may change the <var>toplevel</var>,
and returns the result.</li>

<li><code>(define-into <var>toplevel</var> <var>symbol</var> <var>obj</var>)</code>. This is the same as executing the
top-level form <code>(define <var>symbol</var> <var>obj</var>)</code> in the given <code>toplevel</code>.</li>

<li><code>(gensym)</code>. Generates a new uninterned symbol. An uninterned symbol differs from any symbol that can be
typed or read from a file.</li>

<li><code>(interned? <var>symbol</var>)</code>. Returns <code>#t</code> if <var>symbol</var> is an interned symbol, or
<code>#f</code> otherwise.</li>

</ulp>

</section>

<section name="xom"><title>Expression Object Model Functions</title>

<p>These functions allow you to build expressions using the Expression Object Model.</p>

<p>First, here are some functions to test for the various types of objects.</p>

<ulp>

<li><code>(xom-expression-source? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var>
is an Expression Source object; otherwise returns <code>#f</code>.</li>

<li><code>(xom-expression? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var>
is a compiled Expression object; otherwise returns <code>#f</code>.</li>

<li><code>(xom-envspec? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is an
Environment Specification; otherwise returns <code>#f</code>. An Environment Specification is a list of symbols
in an environment. <code>xom-get-requirements</code> returns the Environment Specification that indicates
what symbols have to be in the environment of a given Expression Source object.</li>

<li><code>(xom-envdesc? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is an
Environment Description; otherwise returns <code>#f</code>. An Environment Description is a list of symbols
in an environment along with each symbol&rsquo;s index into the environment. You need an Environment Description
in order to compile an Expression Source into an Expression.</li>

<li><code>(xom-environment? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is
an Environment; otherwise returns <code>#f</code>.</li>

<li><code>(xom-let-clause? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is
a Let Clause; otherwise returns <code>#f</code>.</li>

<li><code>(xom-placeholder? <var>obj</var>)</code>. Returns <code>#t</code> if and only if <var>obj</var> is
a Placeholder; otherwise returns <code>#f</code>.</li>

</ulp>

<p>The following functions allow the creation of Expression Source objects.</p>

<ulp>

<li><code>(xom-literal <var>value</var>)</code>. Creates and returns an Expression Source object which
returns the literal object <var>value</var>.</li>

<li><code>(xom-var-ref <var>var</var>)</code>. Creates and returns an Expression Source object which
references the variable <var>var</var>.</li>

<li><code>(xom-var-set <var>var</var> <var>value</var>)</code>. Creates and returns an Expression Source object
which sets the variable <var>var</var> to the result of evaluating the Expression Source object <var>value</var>.</li>

<li><code>(xom-make-unspecified)</code>. Creates and returns an Expression Source object which always returns
the unspecified value.</li>

<li><code>(xom-begin <var>expr</var> <var>...</var>)</code>. Creates and returns an Expression Source object which
evaluates the Expression Source objects <var>expr</var> <var>...</var> from left to right and returns the value
of the last one. If <code>xom-begin</code> is called with no parameters, it acts like
<code>xom-make-unspecified</code>.</li>

<li><code>(xom-if-then <var>test</var> <var>consequence</var>)</code>. Creates and returns an Expression Source
object which acts like <code>(if <var>test</var> <var>consequence</var>)</code>. The arguments must be Expression
Source objects.</li>

<li><code>(xom-if-then-else <var>test</var> <var>consequence</var> <var>alternate</var>)</code>. Creates and
returns an Expression Source object which acts like <code>(if <var>test</var> <var>consequence</var>
<var>alternate</var>)</code>. The arguments must be Expression Source objects.</li>

<li><code>(xom-lambda <var>paramList</var> <var>body</var>)</code>. Creates and returns an Expression Source
object which acts like <code>lambda</code>. The <var>paramList</var> can be a list of symbols, a symbol, or a
dotted list of symbols. <var>body</var> must be an Expression Source object.</li>

<li><code>(xom-invocation <var>expr1</var> <var>expr2</var> <var>...</var>)</code>. Creates and returns an
Expression Source object which evaluates the <var>expr</var> values in some order, then expects the first to
have returned a procedure object, which will be called, passing the values of the others as arguments. All
the arguments to <code>xom-invocation</code> must be Expression Source objects.</li>

<li><code>(xom-and <var>expr</var> <var>...</var>)</code>. Creates and returns an Expression Source object
which acts like the short-circuiting syntax <code>(and <var>expr</var> <var>...</var>)</code>. All the
arguments must be Expression Source objects.</li>

<li><code>(xom-or <var>expr</var> <var>...</var>)</code>. Creates and returns an Expression Source object
which acts like the short-circuiting syntax <code>(or <var>expr</var> <var>...</var>)</code>. All the
arguments must be Expression Source objects.</li>

<li><code>(xom-quasi-cons <var>car</var> <var>cdr</var>)</code>. Creates and returns an Expression Source
object which evaluates <var>car</var> and <var>cdr</var>, which must be Expression Source objects, and returns
their <code>cons</code>. This, and all the <code>xom-quasi</code> functions, are used in the implementation of
quasiquotation.</li>

<li><code>(xom-quasi-append <var>l1</var> <var>l2</var>)</code>. Creates and returns an Expression Source
object which evaluates <var>l1</var> and <var>l2</var> and returns the result of
<code>(append <var>l1r</var> <var>l2r</var>)</code>, where <var>l1r</var> is the result of evaluating <var>l1</var>
and <var>l2r</var> is the result of evaluating <var>l2</var>. <var>l1</var> and <var>l2</var> must be
Expression Source objects.</li>

<li><code>(xom-quasi-list-to-vector <var>list</var>)</code>. Creates and returns an Expression Source object
which evaluates <var>list</var>, which must be an Expression Source object, expecting to receive a list, which
it then converts to a vector.</li>

<li><code>(xom-let-clause <var>var</var> <var>value</var>)</code>. Creates and returns a Let Clause object.
<var>var</var> must be a symbol naming a variable, and <var>value</var> must be an Expression Source object which
will be evaluated in order to compute the value of the variable.</li>

<li><code>(xom-let <var>let-clause1</var> <var>let-clause2</var> <var>...</var> <var>body</var>)</code>. Creates
and returns an Expression Source object that acts like the <code>let</code> syntax. The <var>let-clause</var> arguments
must all be Let Clauses, and the <var>body</var> must be an Expression Source object.</li>

<li><code>(xom-let* <var>let-clause1</var> <var>let-clause2</var> <var>...</var> <var>body</var>)</code>. Creates
and returns an Expression Source object that acts like the <code>let*</code> syntax. The <var>let-clause</var> arguments
must all be Let Clauses, and the <var>body</var> must be an Expression Source object.</li>

<li><code>(xom-letrec <var>let-clause1</var> <var>let-clause2</var> <var>...</var> <var>body</var>)</code>. Creates
and returns an Expression Source object that acts like the <code>letrec</code> syntax. The <var>let-clause</var> arguments
must all be Let Clauses, and the <var>body</var> must be an Expression Source object.</li>

<li><code>(xom-letrec* <var>let-clause1</var> <var>let-clause2</var> <var>...</var> <var>body</var>)</code>. Creates
and returns an Expression Source object that acts like the <code>letrec*</code> syntax. The <var>let-clause</var>
arguments must all be Let Clauses, and the <var>body</var> must be an Expression Source object.</li>

<li><code>(xom-let-loop <var>loopname</var> <var>let-clause</var> <var>...</var> <var>body</var>)</code>. Creates
and returns an Expression Source object that acts like the <code>let <var>loop</var></code> syntax. <var>loopname</var>
must be a symbol. The <var>let-clause</var> arguments must all be Let Clauses, and the <var>body</var> must be an
Expression Source object.</li>

<li><code>(xom-catch <var>handler</var> <var>body</var>)</code>. Creates and returns an Expression Source object
that acts like the syntax <code>(catch <var>handler</var> <var>body</var>)</code>. The arguments must be Expression
Source objects.</li>

<li><code>(xom-dynamic-wind <var>enter</var> <var>body</var> <var>exit</var>)</code>. Creates and returns an Expression
Source object that acts like the syntax <code>(dynamic-wind <var>enter</var> <var>body</var> <var>exit</var>)</code>.
The arguments must be Expression Source objects.</li>

</ulp>

<p>The following are Placeholder functions. A Placeholder stands in for an Expression Source object that has not been
generated yet. A Placeholder must be filled in before the expression containing it can be queried or compiled.
Placeholders can be used to generate directed acyclic graphs, but if they are used to generate cycles, the compiler
will die with a stack overflow.</p>

<ulp>

<li><code>(xom-placeholder)</code>. Creates and returns a new Placeholder.</li>

<li><code>(xom-set-placeholder! <var>placeholder</var> <var>value</var>)</code>. Sets the Placeholder
<var>placeholder</var>&rsquo;s value to the Expression Source object <var>value</var>.</li>

<li><code>(xom-is-placeholder-set? <var>placeholder</var>)</code>. Returns <code>#t</code> if the
Placeholder <var>placeholder</var> has been set, and <code>#f</code> otherwise. In the current implementation,
a placeholder <i>can</i> be set more than once, but it retains only the value it was last set to.</li>

</ulp>

<p>The following functions have to do with the compilation and evaluation of Expression Source objects.</p>

<ulp>

<li><code>(xom-get-requirements <var>expr</var>)</code>. Creates and returns an Environment Specification indicating
all variables that are free in the Expression Source object <var>expr</var>.</li>

<li><code>(envspec-&gt;list <var>envspec</var>)</code>. Converts an Environment Specification to a list of symbols and
returns the list.</li>

<li><code>(list-&gt;envdesc <var>list</var>)</code>. Expects <var>list</var> to be a list of symbols, and converts it
to an Environment Description. (An Environment Description maps symbols to integer indexes into the environment.)</li>

<li><code>(envspec-&gt;envdesc <var>envspec</var>)</code>. Converts an Environment Specification to an Environment
Description. This is similar to <code>(list-&gt;envdesc (envspec-&gt;list <var>envspec</var>))</code>, but faster
and more efficient.</li>

<li><code>(envdesc-&gt;vector <var>envdesc</var>)</code>. Creates a vector of symbols where each symbol is in the
place where its value should be in the environment.</li>

<li><code>(envdesc-&gt;envspec <var>envdesc</var>)</code>. Creates an Environment Specification listing the variables
that are in the Environment Description <var>envdesc</var>.</li>

<li><code>(xom-envdesc-lookup <var>envdesc</var> <var>symbol</var>)</code>. Finds <var>symbol</var> in the Environment
Description <var>envdesc</var> and returns its index.</li>

<li><code>(xom-envdesc-count <var>envdesc</var>)</code>. Finds out how many indexes are in the given Environment
Description. This is similar to <code>(vector-length (envdesc-&gt;vector <var>envdesc</var>))</code>, but faster
and more efficient.</li>

<li><code>(xom-get-empty-envdesc)</code>. Returns an Environment Description for the empty Environment.</li>

<li><code>(xom-get-empty-environment)</code>. Returns the empty Environment.</li>

<li><code>(vector-&gt;environment <var>vector</var></code>). Creates and returns an Environment where each
variable contains the contents of the vector at that index. Calling <code>(vector-&gt;environment (envdesc-&gt;vector
<var>envdesc</var>))</code> for some Environment Description <var>envdesc</var> would create an Environment
where every variable&rsquo;s value was equal to the variable&rsquo;s name.</li>

<li><code>(xom-compile <var>exprsrc</var> <var>envdesc</var>)</code>. Compiles the Expression Source <var>exprsrc</var>
so that it can be evaluated in the environment described by the Environment Description <var>envdesc</var>.
Returns a compiled Expression object.</li>

<li><code>(xom-eval <var>expr</var> <var>env</var>)</code>. Evaluates the compiled Expression object <var>expr</var>
in the Environment <var>env</var> and returns the result.</li>

</ulp>

</section>

</section>

<section name="pascalesque"><title>The Pascalesque Compiler</title>

<p>Sunlit World Scheme now includes a compiler that produces MSIL code for immediate execution. Code compiled this way
runs much more quickly than code in plain Scheme.</p>

<p>The compiler and the language it compiles are both called Pascalesque because they were originally intended to be
similar to Pascal. However, the language evolved somewhat during its definition and began to resemble Pascal less and
less.</p>

<p>The <code>make-bitmap-maker</code> function accepts Pascalesque expressions and uses them to produce fast bitmap
conversion functions.</p>

<p>Pascalesque expressions can be quoted or can be generated and returned by Scheme functions.</p>

<p>Pascalesque does not have <code>call/cc</code>, but it has proper tail
calls, <code>lambda</code>, <code>letrec</code>, and <code>let-loop</code>.</p>

<p>Another function that takes a Pascalesque expression is <code>(pascalesque <var>expr</var>)</code>. The
<var>expr</var> must evaluate to a Pascalesque lambda expression. The <code>pascalesque</code> function will build a
Scheme procedure wrapper around the function so that it can be called from Scheme.</p>

<p>Most Pascalesque operations are defined as syntaxes instead of functions.</p>

<section name="pascalesque_types"><title>Pascalesque Types</title>

<p>In Pascalesque, all variables and parameters are strongly typed. The types are as follows.</p>

<ul>

<li><code>byte</code></li>
<li><code>short</code></li>
<li><code>int</code></li>
<li><code>long</code></li>
<li><code>sbyte</code></li>
<li><code>ushort</code></li>
<li><code>uint</code></li>
<li><code>ulong</code></li>
<li><code>float</code></li>
<li><code>double</code></li>
<li><code>bool</code></li>
<li><code>intptr</code></li>
<li><code>uintptr</code></li>
<li><code>char</code></li>
<li><code>void</code></li>

</ul>

<p>All of these are the same as their C# equivalents, except of course that C# does not have keywords
for <code>System.IntPtr</code> and <code>System.UIntPtr</code>.</p>

<p>You cannot declare parameters or variables of type <code>void</code>.</p>

<p>The following other types are available:</p>

<ulp>

<li><code>(array-of <var>type</var>)</code>. Represents a dot-Net array of the given type.</li>

<li><code>(action <var>type1</var> <var>...</var>)</code>. Represents
the <code>System.Action&lt;<var>type1</var>,<var>...</var>&gt;</code> delegate type. The minimum number of types that
must be specified is zero.</li>

<li><code>(func <var>type1</var> <var>...</var> <var>returnType</var>)</code>. Represents
the <code>System.Func&lt;<var>type1</var>,<var>...</var>,<var>returnType</var>&gt;</code> delegate type. The minimum
number of types that must be specified is one, for the return type.</li>

<li><code>(tuple <var>type1</var> <var>...</var>)</code>. Represents
the <code>System.Tuple&lt;<var>type1</var>,<var>...</var>&gt;</code> type. At least one type must be specified; the
maximum number of types supported is seven.</li>

<li><code>bitmap</code>. Represents <code>System.Drawing.Bitmap</code>.</li>

<li><code>bitmapdata</code>. Represents <code>System.Drawing.Imaging.BitmapData</code>.</li>

<li><code>byterect</code>. Represents <code>ExprObjModel.Procedures.ByteRectangle</code>.</li>

<li><code>sba</code>. Represents <code>ExprObjModel.Procedures.SchemeByteArray</code>.</li>

<li><code>object</code>. Represents <code>System.Object</code>.</li>

<li><code>string</code>. Represents <code>System.String</code>.</li>

<li><code>exception</code>. Represents <code>System.Exception</code>.</li>

<li><code>idisposable</code>. Represents <code>System.IDisposable</code>.</li>

<li><code>(type-named <var>name</var> <var>generic-arg</var> <var>...</var>)</code>. Finds the type with the given
name. <var>name</var> must be a string, such as <code>&quot;System.Collections.Generic.List`1&quot;</code>
or <code>&quot;System.DateTime&quot;</code>. If the type is generic, you must specify appropriate generic
arguments. The type&rsquo;s assembly must be currently loaded.</li>


</ulp>

<p>Delegates generated by the Pascalesque <code>lambda</code> or <code>let-loop</code> expressions are always of
an <code>action</code> or <code>func</code> type.</p>

</section>

<section name="pascalesque_literals"><title>Pascalesque Literals</title>

<p>Pascalesque has a different syntax for literals, owing to the need to identify the types of the literals.</p>

<ul>

<li><code>#t</code>, the boolean true value.</li>
<li><code>#f</code>, the boolean false value.</li>
<li><code>(byte <var>value</var>)</code>, a byte literal.</li>
<li><code>(short <var>value</var>)</code>.</li>
<li><code>(int <var>value</var>)</code>.</li>
<li><code>(long <var>value</var>)</code>.</li>
<li><code>(sbyte <var>value</var>)</code>.</li>
<li><code>(ushort <var>value</var>)</code>.</li>
<li><code>(uint <var>value</var>)</code>.</li>
<li><code>(ulong <var>value</var>)</code>.</li>
<li><code>(float <var>value</var>)</code>.</li>
<li><code>(double <var>value</var>)</code>.</li>

</ul>

<p>A string is encoded as a literal of type <code>System.String</code>.</p>

</section>

<section name="pascalesque_basics"><title>Basic Syntaxes</title>

<p>Here are the basic Pascalesque syntaxes.</p>

<ulp>

<li><var>symbol</var>. A variable reference.</li>

<li><code>(set! <var>symbol</var> <var>value</var>)</code>. Sets the given variable to the given value. The type
of <var>value</var> must match the declared type of the variable. The type of the <code>set!</code> expression itself
is <code>void</code>.</li>

<li><code>(begin <var>expr1</var> <var>...</var>)</code>. Executes the given expressions for their side effects,
discarding any return values except the last. The type of the <code>begin</code> is the type of the last expression.
An empty <code>begin</code> expression is allowed and has a type of <code>void</code>. A <code>begin</code> with only
one item is allowed and is guaranteed to have no overhead above what the item would have had itself.</li>

<li><code>(nop)</code>. Performs no operation. This expression has a type of <code>void</code> and causes no code
to be emitted. It is the same as an empty <code>begin</code> expression.</li>

<li><code>(if <var>test</var> <var>consequent</var> <var>alternate</var>)</code>. Executes <var>test</var>, which must
be of type <code>bool</code>, then executes either <var>consequent</var> (if <var>test</var> is <code>#t</code>) or
<var>alternate</var> (if <var>test</var> is <code>#f</code>) and returns the result. <var>consequent</var> and
<var>alternate</var> must be of the same type.</li>

<li><code>(while <var>pre</var> <var>test</var> <var>post</var>)</code>. Executes <var>pre</var>, then executes
<var>test</var>. <var>test</var> must be of type <code>bool</code>. If <code>test</code> is true, executes
<var>post</var> and then jumps back to execute <var>pre</var> and then <var>test</var> again. The type of this
expression is the type of <var>pre</var>.</li>

<li><code>(let (<var>vardef</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Each <var>vardef</var> is a
three-item list of the form <code>(<var>type</var> <var>symbol</var> <var>value</var>)</code>. The <var>value</var>
expressions are evaluated first, then the results of these evaluations, which must match the given types exactly, are
assigned to variables named by the <var>symbol</var>s. Finally, the <var>body</var> expressions (which are treated as
a single <code>begin</code> expression) are evaluated in the resulting environment.</li>

<li><code>(let* (<var>vardef</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Similar to <code>let</code>
except that each <var>vardef</var> is evaluated in an environment where the previous variables are defined.</li>

<li><code>(letrec (<var>vardef</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Similar to
<code>let</code> and <code>let*</code>, except that the variables are defined but uninitialized first, then all the
initialization expressions are evaluated in an environment where all the variables are accessible. This is most
commonly used to define mutually recursive functions with <code>lambda</code>.</li>

<li><code>(let-loop <var>returntype</var> <var>loopname</var> (<var>vardef</var> <var>...</var>) <var>body</var>
<var>...</var>)</code>. Creates a loop. <var>loopname</var> is bound to a procedure that accepts values for the
variables as parameters and executes <var>body</var>. The <var>vardef</var> forms give the initial values for the
parameters. <var>returntype</var> specifies the return type of the loop procedure.</li>

<li><code>(lambda (<var>paramdef</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Creates a procedure.
A <var>paramdef</var> is a list of the form <code>(<var>type</var> <var>symbol</var>)</code>. These procedures are
delegates of one of the <code>func</code> or <code>action</code> types.</li>

<li><code>(invoke <var>func</var> <var>arg</var> <var>...</var>)</code>. Invokes a delegate. The delegate can be of
any type but the parameters must match exactly.</li>

<li><code>(switch <var>expr</var> <var>clause</var> <var>...</var>)</code>. Switches off to various <var>clause</var>
items on the basis of <var>expr</var>. The <var>expr</var> must be of type <code>uint</code>. Each <var>clause</var>
must be of the form <code>((<var>i</var> <var>...</var>) <var>body</var> <var>...</var>)</code>, except that the last
one may be of the form <code>(else <var>body</var> <var>...</var>)</code>. Each <var>i</var> must be an unsigned
integer (but not an unsigned integer <i>expression</i>; it is not necessary or proper to write <code>(uint
<var>i</var>)</code>, and Pascalesque cannot do any computation to fill these). No <var>i</var> can appear more than
once. The type of the <code>switch</code> is the type of the last <var>expr</var> in all clauses, which must be the
same. If no <code>else</code> clause is specified, the type must be <code>void</code>.</li>

<li><code>(cond <var>clause</var> <var>...</var>)</code>. Considers clauses in turn and executes the first one whose
condition is true. The clauses must be of the form <code>(if <var>test</var> <var>expr</var> <var>...</var>)</code>,
except that the last can be of the form <code>(else <var>expr</var> <var>...</var>)</code>.</li>

<li><code>(pin (<var>pinclause</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Pins arrays in memory so
that they will not be moved by the garbage collector. The pinned arrays can be referenced with the unsafe syntaxes,
e.g., <code>poke!</code> and <code>peek</code>, defined below. Each <var>pinclause</var> is of the form
<code>(<var>name</var> <var>arr</var>)</code>. <var>arr</var> is an expression that should evaluate to an array of an
integral or floating-point type. <var>name</var> is the name of a variable of type <code>intptr</code> that will
contain the pointer to the pinned array. The <var>body</var> expressions are treated the same as if they had appeared
inside a <code>begin</code>. The <var>body</var> expressions are not in a tail position because they must execute to
completion before the arrays are unpinned. The type of the <code>pin</code> expression is the same as the type of the
last <var>body</var> expression.</li>

<li><code>(and <var>expr</var> <var>...</var>)</code>. Evaluates the <var>expr</var> expressions from left to right,
but stops and returns <code>#f</code> if any expression returns <code>#f</code>. If all the expressions return
<code>#t</code>, returns <code>#t</code>. Each expression must be of type <code>bool</code>. An <code>and</code> with
no expressions is allowed and returns <code>#t</code>.</li>

<li><code>(or <var>expr</var> <var>...</var>)</code>. Evalutes the <var>expr</var> expressions from left to right, but
stops and returns <code>#t</code> if any expression returns <code>#t</code>. If all the expressions return
<code>#f</code>, returns <code>#f</code>. Each expression must be of type <code>bool</code>. An <code>or</code> with
no expressions is allowed and returns <code>#f</code>.</li>

<li><code>(pfor <var>s</var> <var>e</var> <var>proc</var>)</code>. Parallel-for. Passes every <code>int</code> from
<var>s</var> to <var>e</var>, including <var>s</var> but not including <var>e</var>, to <var>proc</var>, which must be
of type <code>(action int)</code>. Multiple calls to <var>proc</var> may take place in parallel. The <code>pfor</code>
expression is of type <code>void</code>. This syntax calls the function
<code>System.Threading.Tasks.Parallel.For</code>.</li>

<li><code>(try-block <var>clause</var> <var>...</var>)</code>. The clauses
are:</li>

<ulp>

<li><code>(try <var>expr</var> <var>...</var>)</code>, which is required to appear exactly once and must be
first,</li>

<li><code>(catch (<var>type</var> <var>var</var>) <var>expr</var> <var>...</var>)</code>, which may appear zero or
more times, and</li>

<li><code>(finally <var>expr</var> <var>...</var>)</code>, which may appear at the end, up to one time.</li>

</ulp>

<li><code>(using* (<var>vardef</var> <var>...</var>) <var>body</var> <var>...</var>)</code>. Similar
to <code>let*</code> but uses internal <code>try-block</code>s to ensure that any disposable objects in the variables
are disposed before the block exits.</li>

<li><code>(throw <var>type</var> <var>expr</var>)</code>. Throws an exception given by <var>expr</var> instead of
returning a value of type <var>type</var> (which may be <code>void</code>). <var>type</var> is provided so that you
can satisfy type matching requirements; for example, when <code>if</code> requires that the <var>consequent</var>
and <var>alternate</var> return the same type, and one side throws an exception, you should set <var>type</var> to be
whatever the other side returns. You can think of <var>type</var> as the type of the value which is <i>not</i>
returned.</li>

<li><code>(new-exception <var>msg</var>)</code>. Creates a new object of type <code>System.Exception</code> given the
string <var>msg</var>.</li>

<li><code>(null? <var>var</var>)</code>. Checks to see if <var>var</var>, a variable of some class type,
is <code>null</code>. Returns a boolean.</li>

<li><code>(is? <var>type</var> <var>expr</var>)</code>. Evaluates <var>expr</var>, an expression returning an instance
of some class, and returns <code>#t</code> if the result is of type <var>type</var>, and returns <code>#f</code>
otherwise.</li>

<li><code>(cast-to <var>type</var> <var>expr</var>)</code>. Evalutes <var>expr</var>, an expression that returns some
object, and casts it to the type <var>type</var>, which must be a class type. This may throw
a <code>ClassCastException</code>.</li>

<li><code>(box <var>expr</var>)</code>. Evaluates <var>expr</var>, an expression that Pascalesque regards as having a
value type, and casts it to <code>System.Object</code>.</li>

<li><code>(unbox <var>type</var> <var>expr</var>)</code>. Unboxes <var>expr</var>, a boxed value type. <var>expr</var>
should be an expression considered by Pascalesque to have type <code>System.Object</code>, but <code>is?</code> should
reveal it to have type <var>type</var>.</li>

<li><code>(call (<var>criterion1</var> <var>...</var>) <var>type</var> <var>method-name</var>
(<var>param-type-1</var> <var>...</var>) <var>arg1</var> <var>...</var>)</code>. Calls the method of <var>type</var>
named <var>method-name</var> and matching the given criteria, taking parameters of the given types. (The criteria are
optional and are only used to narrow the search. The search must yield exactly one method.) The arguments must match
the parameter types. If the method is an instance method, an instance must be the first argument. The criteria
are:</li>

<ul>
<li><code>static</code></li>
<li><code>instance</code></li>
<li><code>public</code></li>
<li><code>nonpublic</code></li>
<li><code>special</code></li>
<li><code>nonspecial</code></li>
</ul>

<li><code>(get-property (<var>criterion1</var> <var>...</var>) <var>type</var> <var>property-name</var>
(<var>indexer-type-1</var> <var>...</var>) <var>arg1</var> <var>...</var>)</code>. Gets the property
of <var>type</var> named <var>property-name</var> and matching the given criteria, taking indexing parameters of the
given types. (The criteria are only used to narrow the search. A property is considered &ldquo;public&rdquo; if either
its getter or setter is public, and it is considered static if neither its getter nor its setter is non-static.) The
arguments must match the parameter types. If the property is an instance property, an instance must be the first
argument.</li>

<li><code>(set-property (<var>criterion1</var> <var>...</var>) <var>type</var> <var>property-name</var>
(<var>indexer-type-1</var> <var>...</var>) <var>arg1</var> <var>...</var> <var>value</var>)</code>. Sets the property
of <var>type</var> named <var>property-name</var> and matching the given criteria, taking indexing parameters of the
given types. The arguments must match the parameter types. If the property is an instance property, an instance must
be the first argument.</li>

<li><code>(new <var>type</var>
(<var>param-type-1</var> <var>...</var>) <var>arg1</var> <var>...</var>)</code>. Constructs a new object of
type <var>type</var> by calling the public constructor with the given parameters. The arguments must match the
parameter types.</li>

<li><code>(tuple-first <var>tuple</var>)</code>, <code>(tuple-second <var>tuple</var>)</code>, etc., are defined up
to <code>tuple-seventh</code>. They retrieve the given element in the given <var>tuple</var>.</li>

</ulp>

</section>

<section name="pascalesque_conversions"><title>Pascalesque Type Conversions</title>

<p>The following syntaxes allow conversion between types in Pascalesque. They use the MSIL conversion instructions,
the ones which do not detect overflow.</p>

<ul>

<li><code>(to-byte <var>expr</var>)</code>. Converts the type of <var>expr</var> to byte.</li>

<li><code>(to-short <var>expr</var>)</code>. Converts the type of <var>expr</var> to short.</li>

<li><code>(to-int <var>expr</var>)</code>. And so forth.</li>

<li><code>(to-long <var>expr</var>)</code>.</li>

<li><code>(to-sbyte <var>expr</var>)</code>.</li>

<li><code>(to-ushort <var>expr</var>)</code>.</li>

<li><code>(to-uint <var>expr</var>)</code>.</li>

<li><code>(to-ulong <var>expr</var>)</code>.</li>

<li><code>(to-intptr <var>expr</var>)</code>.</li>

<li><code>(to-uintptr <var>expr</var>)</code>.</li>

<li><code>(to-float <var>expr</var>)</code>.</li>

<li><code>(to-double <var>expr</var>)</code>.</li>

</ul>

</section>

<section name="pascalesque_regardas"><title>Pascalesque Regard-As Conversions</title>

<p>The following syntaxes allow conversion without emitting any instructions. This is useful because MSIL represents
these data types using a smaller set of types.</p>

<ul>

<li>The types <code>byte</code>, <code>sbyte</code>, <code>short</code>, <code>ushort</code>, <code>int</code>,
and <code>uint</code> are all represented on the stack by a 32-bit integer of indeterminate signedness.</li>

<li>The types <code>intptr</code> and <code>uintptr</code> are represented on the stack by a &ldquo;native integer&rdquo;
of indeterminate signedness.</li>

<li>The types <code>long</code> and <code>ulong</code> are represented on the stack by a 64-bit integer of
indeterminate signedness.</li>

<li>The types <code>float</code> and <code>double</code> are represented on the stack by a 64-bit floating-point number.</li>

<li>Objects of class type are represented on the stack by object references, which cannot be regarded as any of the
other types.</li>

</ul>

<p>Regard-as allows any type to be interpreted as any other type with the same underlying type. So it is possible to
regard an int as a short, but it is not possible to regard a long as an int, because they have different underlying
types. You have to use a true conversion instruction in such cases.</p>

<p>This raises the question of what the true conversion instructions do when the underlying types are the same. My
impression is that they do bit-masking or rounding; for example, running <code>to-byte</code> on an <code>int</code>
will produce a value that is guaranteed to fit in a byte.</p>

<p>The regard-as instructions are:</p>

<ul>

<li><code>(as-byte <var>expr</var>)</code></li>

<li><code>(as-short <var>expr</var>)</code></li>

<li><code>(as-int <var>expr</var>)</code></li>

<li><code>(as-long <var>expr</var>)</code></li>

<li><code>(as-sbyte <var>expr</var>)</code></li>

<li><code>(as-ushort <var>expr</var>)</code></li>

<li><code>(as-uint <var>expr</var>)</code></li>

<li><code>(as-ulong <var>expr</var>)</code></li>

<li><code>(as-intptr <var>expr</var>)</code></li>

<li><code>(as-uintptr <var>expr</var>)</code></li>

<li><code>(as-float <var>expr</var>)</code></li>

<li><code>(as-double <var>expr</var>)</code></li>

</ul>

</section>

<section name="pascalesque_arithlogic"><title>Arithmetic and Logic</title>

<p>Pascalesque has the following syntaxes for arithmetic and logic. Unlike Scheme, the number of arguments in these
syntaxes is fixed. The arguments must be of the same type (this is more strict than the underlying MSIL) and the
result is of the same type as the arguments. Exceptions are noted below.</p>

<ul>

<li><code>(+ <var>a</var> <var>b</var>)</code>.</li>

<li><code>(- <var>a</var> <var>b</var>)</code>.</li>

<li><code>(* <var>a</var> <var>b</var>)</code>.</li>

<li><code>(/ <var>a</var> <var>b</var>)</code>.</li>

<li><code>(% <var>a</var> <var>b</var>)</code>. Modulus.</li>

<li><code>(logand <var>a</var> <var>b</var>)</code>. Logical AND. Works only with integer arguments.</li>

<li><code>(logior <var>a</var> <var>b</var>)</code>. Logical inclusive OR.</li>

<li><code>(logxor <var>a</var> <var>b</var>)</code>. Logical exclusive OR.</li>

<li><code>(shl <var>a</var> <var>b</var>)</code>. <var>a</var> must be of integral type and <var>b</var> must be of
type <code>int</code> or <code>intptr</code>. The shift count must be non-negative and smaller than the number of bits
in the value to be shifted. The return type is the same as the type of <var>a</var>.</li>

<li><code>(shr <var>a</var> <var>b</var>)</code>. <var>a</var> must be of integral type and <var>b</var> must be of
type <code>int</code> or <code>intptr</code>. The shift count must be non-negative and smaller than the number of bits
in the value to be shifted. The compiler chooses a signed or unsigned shift based on the type of <var>a</var>. The
return type is the same as the type of <var>a</var>.</li>

<li><code>(invert <var>a</var>)</code>. Flips all the bits in <var>a</var>, which must be of integral type.</li>

<li><code>(negate <var>a</var>)</code>. Negates <var>a</var>. Overflow is ignored. The argument is always treated as
signed for this operation. The return type is the same as that of the argument.</li>

<li><code>(not <var>a</var>)</code>. <var>a</var> must be of type <code>bool</code>.</li>

<li><code>(&lt; <var>a</var> <var>b</var>)</code>. Returns a boolean.</li>

<li><code>(&lt;= <var>a</var> <var>b</var>)</code>.</li>

<li><code>(&gt; <var>a</var> <var>b</var>)</code>.</li>

<li><code>(&gt;= <var>a</var> <var>b</var>)</code>.</li>

<li><code>(= <var>a</var> <var>b</var>)</code>.</li>

<li><code>(&lt;&gt; <var>a</var> <var>b</var>)</code>. Tests for not-equal.</li>

</ul>

<p>Some syntaxes allow functions from the <code>System.Math</code> class to be used in Pascalesque.</p>

<ul>

<li><code>(abs <var>a</var>)</code>. Calls <code>Math.Abs</code>. The return type will be the same as the type
of <var>a</var>. The supported types
are <code>sbyte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>,
and <code>double</code>.</li>

<li><code>(sign <var>a</var>)</code>. Calls <code>Math.Sign</code>. The return type will be the same as the type
of <var>a</var>. The supported types
are <code>sbyte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>,
and <code>double</code>.</li>

<li><code>(max <var>a</var> <var>b</var>)</code>. Calls <code>Math.Max</code>. Arguments must be of the same type, and
the return type will be the same as the types of the arguments. The supported types
are <code>byte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>sbyte</code>, <code>ushort</code>,
<code>uint</code>, <code>ulong</code>, <code>float</code>, and <code>double</code>.</li>

<li><code>(min <var>a</var> <var>b</var>)</code>. Calls <code>Math.Min</code>. Arguments must be of the same type, and
the return type will be the same as the types of the arguments. The supported types
are <code>byte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>sbyte</code>, <code>ushort</code>,
<code>uint</code>, <code>ulong</code>, <code>float</code>, and <code>double</code>.</li>

</ul>

<p>Some syntaxes from the <code>System.Math</code> class, typically for transcendental functions or rounding, take
arguments only of type <code>double</code>, and return <code>double</code>.</p>

<ul>

<li><code>(acos <var>r</var>)</code>.</li>

<li><code>(asin <var>r</var>)</code>.</li>

<li><code>(atan <var>r</var>)</code>.</li>

<li><code>(atan2 <var>x</var> <var>y</var>)</code>.</li>

<li><code>(ceil <var>x</var>)</code>.</li>

<li><code>(cos <var>a</var>)</code>.</li>

<li><code>(cosh <var>a</var>)</code>.</li>

<li><code>(exp <var>x</var>)</code>.</li>

<li><code>(floor <var>x</var>)</code>.</li>

<li><code>(ieeeremainder <var>x</var> <var>y</var>)</code>.</li>

<li><code>(log <var>m</var>)</code>.</li>

<li><code>(logbase <var>m</var> <var>b</var>)</code>.</li>

<li><code>(log10 <var>m</var>)</code>.</li>

<li><code>(pow <var>b</var> <var>e</var>)</code>.</li>

<li><code>(round <var>x</var>)</code>.</li>

<li><code>(sin <var>a</var>)</code>.</li>

<li><code>(sinh <var>a</var>)</code>.</li>

<li><code>(sqrt <var>x</var>)</code>.</li>

<li><code>(tan <var>a</var>)</code>.</li>

<li><code>(tanh <var>a</var>)</code>.</li>

<li><code>(trunc <var>x</var>)</code>.</li>

</ul>

</section>

<section name="pascalesque_arrays"><title>Pascalesque Arrays</title>

<p>Pascalesque provides some syntaxes to deal with dot-Net arrays.</p>

<ul>

<li><code>(new-array <var>type</var> <var>size</var>)</code>. Creates a new array where the element type
is <var>type</var>. The expression <var>size</var> must be of type <code>int</code>.</li>

<li><code>(array-ref <var>array</var> <var>index</var>)</code>.</li>

<li><code>(array-set! <var>array</var> <var>index</var> <var>val</var>)</code>.</li>

<li><code>(array-length <var>array</var>)</code>. Returns the number of elements.</li>

</ul>

</section>

<section name="pascalesque_unsafe"><title>Unsafe Operations in Pascalesque</title>

<p>These operations deal directly with memory. If not used carefully they can corrupt the program.</p>

<p>All addresses must be of type <code>intptr</code> or <code>uintptr</code>.</p>

<ulp>

<li><code>(poke! <var>addr</var> <var>val</var>)</code>. Writes <var>val</var> to memory at
address <var>addr</var>. <var>val</var> can be of any integral or floating-point type. The number of bytes written
depends on the type. This expression returns <code>void</code>.</li>

<li><code>(peek <var>type</var> <var>addr</var>)</code>. Reads a value of type <var>type</var> from memory at address
<var>addr</var>, and returns it. <var>type</var> can be any integral or floating-point type.</li>

<li><code>(memset! <var>dest</var> <var>b</var> <var>count</var>)</code>. Sets bytes of memory to the
byte <var>b</var> starting at address <var>dest</var> and proceeding for <var>count</var> bytes. This expression
returns <code>void</code>.</li>

<li><code>(memcpy! <var>dest</var> <var>src</var> <var>count</var>)</code>. Copies <var>count</var> bytes of memory
from <var>src</var> to <var>dest</var>. Results are undefined if the memory regions overlap. This expression
returns <code>void</code>.</li>

</ulp>

</section>

<section name="pascalesque_bitmap"><title>Pascalesque Bitmap Syntaxes</title>

<p>Pascalesque was originally invented for the purpose of quickly creating bitmaps with <code>make-bitmap-maker</code>.
These functions promise to make <code>make-bitmap-maker</code> obsolete.</p>

<p>Bitmaps created by these functions, and regions locked, are always in the
format <code>System.Drawing.Imaging.PixelFormat.Format32bppRgb</code>.</p>

<ulp>

<li><code>(create-bitmap <var>width</var> <var>height</var>)</code>. Creates and returns a new bitmap with
the given <var>width</var> and <var>height</var>. <var>width</var> and <var>height</var> must be of type <code>int</code>.</li>

<li><code>(lock-bits! <var>bmp</var> <var>mode</var>)</code>. Locks the bits in the bitmap <var>bmp</var> and returns
an object of type <code>bitmapdata</code>. <var>mode</var> is not a Pascalesque expression. It can be the
symbol <code>read</code>, the symbol <code>write</code>, or the symbol <code>read-write</code>. It is important to
ensure that <code>unlock-bits!</code> is used later.</li>

<li><code>(unlock-bits! <var>bmp</var> <var>bitmapdata</var>)</code>. Unlocks the bits in the bitmap <var>bmp</var>
that are indicated by <var>bitmapdata</var>.</li>

</ulp>

</section>

<section name="pascalesque_misc"><title>Miscellaneous Pascalesque Syntaxes</title>

<p>The remaining Pascalesque syntaxes are as follows.</p>

<ulp>

<li><code>(sba-get-bytes <var>sba</var>)</code>. Gets the <code>(array-of byte)</code> from a Scheme Byte Array.</li>

<li><code>(byterect-get-sba <var>byterect</var>)</code>. Gets the Scheme Byte Array from a byterect.</li>

<li><code>(byterect-get-offset <var>byterect</var>)</code>. Returns the offset from a byterect as an <code>int</code>.</li>

<li><code>(byterect-get-width <var>byterect</var>)</code>. Returns the width as an <code>int</code>.</li>

<li><code>(byterect-get-height <var>byterect</var>)</code>. Returns the height as an <code>int</code>.</li>

<li><code>(byterect-get-stride <var>byterect</var>)</code>. Returns the stride as an <code>int</code>.</li>

<li><code>(bitmapdata-get-height <var>bitmapdata</var>)</code>. Returns the height of a bitmapdata as an <code>int</code>.</li>

<li><code>(bitmapdata-get-width <var>bitmapdata</var>)</code>. Returns the width of a bitmapdata as an <code>int</code>.</li>

<li><code>(bitmapdata-get-stride <var>bitmapdata</var>)</code>. Returns the stride of a bitmapdata as an <code>int</code>.</li>

<li><code>(bitmapdata-get-scan0 <var>bitmapdata</var>)</code>. Returns an <code>intptr</code> containing the address
of the first pixel of the bitmapdata.</li>

</ulp>

</section>

<p>That&rsquo;s the end of the Pascalesque functions.</p>

</section>

<section name="toplevel"><title>Top-Level Forms</title>

<p>Top-level forms are used to load programs and to control the interpreter.</p>

<ulp>

<li><code>(define <var>var</var> <var>value</var>)</code>. <code>define</code> allocates a new variable named
<var>var</var>, evaluates <var>value</var> in a context where <var>var</var> exists but is undefined, and then, like
the <code>set!</code> syntax, sets <var>var</var> to the result.</li>

<li><code>(load <var>filename</var>)</code>. This is used to load a Scheme source-code file into the
interpreter. Every Scheme form in the file is executed until the file ends or the first error is encountered. The
Scheme source file typically uses <code>define</code> to define new functions. At the end of the loading process, the
interpreter is made available again.</li>

<li><code>(load-interactive)</code>. Puts up an &ldquo;Open File&rdquo; dialog and allows the user to select a
<code>.scm</code> file. The file is then loaded as with <code>load</code>.</li>

<li><code>(load-library <var>filename</var>)</code>. This is used to load a dot-Net DLL. The DLL is loaded and
reflected over, and any function bearing an <code>ExprObjModel.SchemeFunctionAttribute</code> is imported into the
interpreter. Any class bearing the <code>ExprObjModel.SchemeSingletonAttribute</code>, if it implements the
<code>ExprObjModel.IProcedure</code> interface, will have one of its instances constructed and added to the
interpreter.</li>

</ulp>

<section name="modules"><title>The Module System</title>

<p>Sunlit World Scheme has a <i>hyper-static global environment.</i> This means that if you <code>define</code> a
variable that already exists, a new variable is created and the old one is permanently shadowed. (The old variable
will be garbage-collected if it is rendered unreachable by this shadowing, but it can still be reached if
any <code>lambda</code> expressions have captured it.) This is deliberately different from the R4RS standard, which
specifies that a <code>define</code> of a variable that already exists acts like <code>set!</code>.</p>

<p>A common textbook example of mutually recursive procedures is <code>odd?</code> and <code>even?</code>, both of
which take non-negative integers as arguments. In standard Scheme you can write:</p>

<ul>

<li><code>(define odd? (lambda (x) (if (= x 0) #f (even? (- x 1)))))</code></li>

<li><code>(define even? (lambda (x) (if (= x 0) #t (odd? (- x 1)))))</code></li>

</ul>

<p>This is wrong and dangerous in Sunlit World Scheme. If <code>even?</code> is undefined, the attempt to define
<code>odd?</code> will fail because of an undefined symbol error. However, suppose <code>even?</code> is defined by
another library or by Scheme itself. In that case, <code>odd?</code> will capture the reference to <i>that</i> version
of <code>even?</code>, and the later definition of <code>even?</code> will not alter the original definition. So the
functions will not actually be mutually recursive. Instead, <code>even?</code> will call <code>odd?</code>, which will
call the <i>old</i> implementation of <code>even?</code>.</p>

<p>The correct way to define these procedures is to create the variables first, then initialize them, as follows.</p>

<ul>

<li><code>(define odd? #f)</code></li>

<li><code>(define even? #f)</code></li>

<li><code>(set! odd? (lambda (x) (if (= x 0) #f (even? (- x 1)))))</code></li>

<li><code>(set! even? (lambda (x) (if (= x 0) #t (odd? (- x 1)))))</code></li>

</ul>

<p>Such an approach makes the procedures mutually recursive, and works regardless of whether definitions
for <code>odd?</code> and <code>even?</code> existed before the new definitions were written.</p>

<p>(It is possible to use three top-level forms instead of four: <code>(define odd? #f)</code>, <code>(define
even? <var>...</var>)</code>, then <code>(set! odd? <var>...</var>)</code>.)</p>

<p>When you load a Scheme file for use as a library, the hyper-static environment makes it impossible for the library
to accidentally <code>set!</code> the internal variables of another library by using <code>define</code>. The library
can still clobber references &mdash; but it cannot clobber values. So if you can still reference one of the
library&rsquo;s functions (and the only reason you wouldn&rsquo;t be able to is because of shadowing), you can be sure
it will behave correctly.</p>

<p>A top-level environment is basically a mapping from symbols to locations. Defining new symbols changes this
mapping, but without changing the values in the locations.</p>

<p>To help battle the clobbering of references, Sunlit World Scheme has a simple module system which allows saving and
restoring top-level environments. These two top-level forms control the module system.</p>

<ulp>

<li><code>(begin-module)</code>. This saves a copy of the top-level environment.</li>

<li><code>(end-module <var>export1</var> <var>...</var>)</code>. This restores a previously saved copy of the
top-level environment. If one or more <var>export</var> symbols are specified, <code>end-module</code> exports them
into the restored environment.</li>

</ulp>

<p>These two functions allow a Sunlit World Scheme module to expose only the functions it wants to export, without
clobbering anything that used to be in the top-level environment.</p>

<p>Top-level environments are saved on a stack so that <code>begin-module</code> and <code>end-module</code> pairs can
be nested. This allows a module to privately use another module.</p>

</section>

</section>

</doc>
